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This reference publication is intended primarily 
for the system programmer who is involved in 
making decisions relating to the components of the 
installations supervisor, file organization and 
program design. To form a single publication, 
this manual brings together and expands upon 
information from many sources. Major topics 
discussed are: 

1. Supervisor Planning Concepts 

2. Data Management 

3. Program Design 

4. Debugging Aids 

For each major section, the Preface lists the most 
closely related publications. For a complete list 
of available publications, see the IBM System/360 
and System/370 Bibliography , GA22-6822. 
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I Third Edition (September 1971) 

This publication was formerly titled IBM System/360 Disk 
Operating System : System Programmer's Guide . Although 
titles of some DOS publications (including this one) have 
been simplified, the change does not affect the contents of 
the publications. 

I This edition replaces and obsoletes GC24- 5073-1. Changes are 
continually made to the specifications herein; before using 
this publication in connection with the operation of IBM 
| systems, consult the latest System/360 and System/370 SRL 
Newsletter, GN20-0360, for the editions that are applicable 
and current. 

Summary of Amendments 

I For a list of changes made in this edition, see page 3. 

Changes or additions to the text and illustrations are 
indicated by a vertical line to the left of the change. 

Requests for copies of IBM publications should be made to 
your IBM representative or to the IBM branch office serving 
your locality. 

A form for readers* comments is provided at the back of this 

I publication. If the form has been removed, comments may be 
addressed to IBM Laboratory, Publications Dept. , P.O. Box 24, 
Oithoorn, Netherlands. 

(c) Copyright International Business Machines Corporation 1969, 1970, 1971 



Summary of Amendments 
for GC24-5073-2 



NEW FUNCTIONS 

This edition documents support for these 
system control and service functions: 

• Independent Directory Read- In Area 
(IDRA) 

• On- Line Test Executive Programs 
(OLTEP) 

• Job Accounting Interface 

• Data Set Security 

• ISAM Track Hold 

• Private Core Image Library (PCIL) 

• Label Cylinder Display (LSERV) 

• Recovery Management Support (RMS) for 
System/370, which consists of Machine 
Check Analysis and Recording (MCAR) 
and Channel Check Handler (CCH) 

• Reliability Data Extractor (RDE) 
function for System/370 

• RETAIN/370 for System/370 

PROGRAM ENHANCEMENTS 

This edition also documents the 
enhancements to these programs: 

• Error Statistics by Tape Volume 
(ESTV) 

• Environmental Recording, Editing, and 
Printing (EREP) 

• DOS Stand-Alone Dump Generator 
(DUMPGEN) 

• Problem Determination Serviceability 
Aids (PDAID) 

• Forced End-of-Volume for Disk macro 
(FEOVD) 



• Directory Service Display (DSERV) 



• Linkage Editor (LNKEDT) 



NEW DEVICES 

This edition also documents support for 
these new devices: 

• IBM 1255 Magnetic Character Reader 

• IBM 2319 Disk Storage 

• IBM 3210 Console Printer-Keyboard 

• IBM 3211 Printer 

• IBM 3215 Console Printer-Keyboard 

• IBM 3420 Magnetic Tape Unit 

MISCELLANEOUS CHANGES 

Rewritten sections: The section on hard 
waits is expanded and rewritten. The 
section on COBOL ANS replaces the COBOL D 
section. A glossary is included. 

ORGANIZATION OF PUBLICATION 

The manual has been reorganized and 
reformatted. Information in Appendixes A 
- L in the previous edition has been 
incorporated into the appropriate 
sections in this edition. The total 
publication has a General Contents, a 
Figure list, and an Index. Each section 
has a Section Otitline and a separate 
figure list. Figure numbers throughout 
the publication are in the form: Figure 
1.3, where 1 is the section number and 3 
is the figure number within that section. 
A tab in the upper right-hand corner of 
the beginning of each section identifies 
the section by number. 
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Preface 



This publication is divided into the 
following four major sections: 



1. Supervisor Planning Concepts 



2. Data Management 



3. Program Design 



4. Debugging Aids 



Data Management 
| DOS Data Management Concepts , GC24-3427. 
| DOS Supervisor and I/O Macros . GC24-5037. 
| DOS DASD Labels . GC24-5072. 



Tape Labels for BPS. BOS. TOS and DOS . 
GC24-5070. 



The Supervisor Planning Concepts section 
describes system residence organization, 
some supervisor tables, optional supervisor 
facilities at a conceptual level, and 
presents guidelines for their 
implementation. The Data Management 
section explains the concepts of file 
organization and data manipulation at the 
physical and logical IOCS levels. The 
Program Design section contains suggestions 
for efficient programming. The topics 
discussed are link editing functions, 
overlay structure, self -relocating 
programs, checkpoint/restart facility, the 
3211 Printer support, and macro writing. 
The Debugging Aids section contains aids 
for debugging problem programs written in 
assembler language, PL/I, FORTRAN, COBOL, 
and RPG. 



Multitasking and link editing examples, 
and physical IOCS, STXIT support, 
self- relocating, and language translator 
sample programs are included. 

Closely related publications by section 
follow. 



Note ; Although titles of some DOS 
publications have been simplified, the 
change does not affect the contents of the 
publications . 



Supervisor Planning Concepts 

DOS System Generation . GC24-5033, 

DOS System Control and Service . 
GC24-5036. 

DOS Operating Guide . GC24-5022. 

DOS Messages . GC24-5074. 



IBM System/360 Principles of Operation , 
GA22-6821. 



IBM System/ 370 Principles of Operation , 
GA22-7000. 



Program Design 

DOS System Control and Service . 
GC24-5036. 

I DOS Supervisor and I/O Macros . GC24-5037. 

IBM System/ 3 60 Disk and Tape Operating 
Systems. Assembler Language . GC24-3414. 



Debugging Aids 

DOS OLTEP . GC24-5086. 

IBM System/ 3 60 Disk and Tape Operating 
Systems. COBOL Programmer's Guide . 
GC24-5025. 

IBM System/360 Disk and Tape Operating 
Systems, PL/I Programmer's Guide . 
GC24-9005. 

IBM System/360 Disk Operating System. 
FORTRAN IV Programmer's Guide , GC28-6397. 

IBM System/360 Disk and Tape Operating 
Systems, Report Program Generator 
Specifications , GC26-3570. 

IBM System/ 360 Disk and Tape Operating 
Systems, Assembler Language , GC24-3414. 

DOS Messages . GC24-5074. 

For further information concerning terms 
referenced in this publication, see the IBM 
Data Processing Glossary , GC20-1699. 
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Introduction 



As a system programmer, you make decisions 
involving the components of your 
installation's supervisor, file 
organization, program design, and so forth. 
From time to time, you may be called upon 
to advise other programmers concerning DOS. 
In order to assist you in this task, this 
publication brings together and expands 
upon information from many sources. It is 
divided into four major sections: 
Supervisor Planning Concepts, Data 
Management, Program Design, and Debugging 
Aids. 

The Supervisor Planning Concepts section 
is of interest to the person (s) responsible 
for tailoring the IBM- supplied Disk 
Operating System to meet the needs of the 
installation. This section describes in 
detail optional supervisor facilities 
available under DOS. Using the information 
presented in this section together with the 
information on main storage requirements 
and implementation procedures found in the 
DOS System Generation listed in the 
Preface , the system programmer can decide 
whether or not to include a particular 
facility within the installation's 
supervisor. Guidelines for implementing 
these facilities at system generation time 
are also presented. 

The Data Management section is of 
interest to the person (s) responsible for 
choosing the type of file organization best 
suited for an application. This section 
discusses data management concepts, the 
advantages and disadvantages of each type 
of file organization (sequential, direct 
access and indexed sequential) and criteria 
for choosing the best file organization and 
retrieval method. 

In addition, data manipulation is 
described at both the physical and logical 
IOCS levels. Detailed information for 
coding at the physical IOCS level is 
included. This section also defines the 



macros for implementing logical IOCS and 
describes the interrelationships of the DTF 
and logic module generation macros. 



The Program Design section is of 
interest to the person (s) responsible for 
program design and implementation. The 
Disk Operating System offers the programmer 
a great deal of flexibility in the 
generation of his system and in its 
operation. This section discusses 
effective use of the linkage editor and the 
checkpoint/restart facility. In addition, 
system programming techniques such as macro 
coding, overlay structure and 
self-relocating programs are discussed. 
The IBM 3211 Printer support is also 
discussed. 

The Debugging Aids section is of 
interest to both the application and system 
programmer. This section describes system 
action on a cancel condition, gives 
register conventions for following program 
flow, describes the types of documentation 
to be gathered for debugging purposes and 
the action to be taken when a hard wait or 
program loop is encountered. Problem 
determination aids are briefly described. 
Aids for debugging problem programs written 
in assembler language, COBOL, FORTRAN, PL/I 
and RPG are given. 



Note ; In case of difference between the 
conventions given in this manual 
for control program functions and 
those appearing in IBM-supplied 
DOS component publications (such 
as guides for language 
translators, sorts, utilities, 
specifications manuals, etc), 
observe the specific restrictions 
of the component. 
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To assist, you in planning a supervisor 
tailored to meet the needs of your 
installation, this section presents the 
organization of a disk resident system as 
received from Program Information 
Department (PID) , describes optional 
supervisor facilities at a conceptual 
level, and presents guidelines for their 
implementation. Those optional facilities 
requiring special consideration are 
described in the order in which they appear 
as parameters within the supervisor 
generation macros. For information on the 
other optional supervisor facilities, see 
the DOS System Generation listed in the 
Preface. 



System Residence Organization 



Figure 1.1 describes the organization of 
the DOS disk resident system. The disk 
resident system may be on an IBM 2311 Disk 
Storage Drive, an IBM 2314 Direct Access 
Storage Facility, or an IBM 2319 Disk 
Storage Facility. The organization of the 
disk pack is as follows: 



System Work Area (Cylinder 0, Tracks 2, 3 
and 4) 



This 3-track area is reserved as a work 
area for the librarian programs and linkage 
editor. The format of the records in the 
librarian area depends on the program using 
the area at a specific time. 



Transient Directory (Cylinder 0, Track 5) 



This single track directory contains 
entries for the A- and B-transient routines 
that are located in the core image library. 
The entries in this directory are taken 
from the core image library directory. 



The core image library phases referenced 
in this directory have phase names prefixed 
by $$A (A— transients) or $$B 
(B- transients) . This directory has a 
maximum capacity of 144 entries for the 
2311, or 270 entries for the 2314/2319. 
Track format is identical to the core image 
library directory. 



IPL (Cylinder 0. Track 0, Records 1 and 2) 

This area contains the IPL bootstrap 
program. 



Volume Label (Cylinder 0, Track 0, Record 
3) 



The volume label contains the address of 
the Volume Table of Contents (VTOC) 
established when the pack was initialized. 



Open Directory (Cylinder 0, Track 6) 



This single track directory contains 
entries for the LIOCS open phases located 
in the core image library. The entries in 
this directory are taken from the core 
image library directory. The core image 
library phases referenced in this directory 
have phase names prefixed by the characters 
$$BO. This directory has a maximum 
capacity of 144 entries for the 2311, or 
270 entries for the 2314/2319. 



System Directory (Cylinder 0, Track 1) 



Library Routine Directory (Cylinder 0, 
Track 7) 



This directory consists of five records 
that make up the system master directory. 
Records 1 through 4 are 80 bytes in length. 

Record 1 contains information describing 
the core image library and directory. 
Records 2 and 3 contain the starting 
address of the relocatable library 
directory and the source statement library 
directory, respectively. Record 4 is not 
used. Record 5 is the IPL loader program 
($$A$IPL2). 



This single track directory contains 
entries for frequently used core image 
library phases, such as job control, 
linkage editor, and so forth. The entries 
in this directory are taken from the core 
image library directory. The core image 
library phases that are placed in this 
directory have phase names prefixed by a $ 
(for example, $LNKEDT). This entry has a 
maximum capacity of 144 entries for the 
2311, or 270 entries for the 2314/2319. 
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Foreground Program Directory (Cylinder 0, 
Track 8) 



This single track directory contains 
entries for the foreground program phases 
located in the core image library. The 
entries in this directory are taken from 
the core image library directory. The core 
image library phases referenced in this 
directory have phase names prefixed by the 
characters FGP. This directory has a 
maximum capacity of 144 entries for the 
2311, or 270 entries for the 2314/2319. 



• Phase name 

• Loading address 

• Number of blocks 

• Entry point 

• Starting disk address in the core image 
library 

• Length of last block 



Phase Directory (Cylinder 0, Track 9) 



This single track directory contains 
entries for the phases of the current BG 
problem program. The entries in this 
directory are constructed by job control 
before each job step is executed in the 
background partition only. They are taken 
from the core image library directory. 

The phase naming conventions that permit 
the use of the phase directory are: 

1. All program names must be unique in 
the first four characters. 

2. The first four characters of the name 
of each phase of a program must be 
identical to the first four characters 
of the program name. All eight 
characters of the first phase name 
must be identical to the program name. 

Example : WXVZPROG 
WXVZPROG - phase 1 
WXVZPH1 - phase 2 
WXVZPH2 - phase 3 

The maximum capacity of this directory is 
144 entries for the 2311 or 270 entries for 
| the 2314/2319. 



Core Image Library Directory 



This directory consists of one or more 
tracks, depending on the allocation 
specified by the user. It contains one 
entry for each of the phases in the core 
image library. 

Note : A phase is an overlay of a 
multiphase program or a complete program if 
not multiphase. 

Each directory entry describes one phase 
in the core image library and contains: 



Core Image Library 



The core image library consists of five or 
more tracks, depending on the allocation 
specified by the user. For the 2311, each 
track contains two blocks with a maximum 
capacity of 1728 bytes. For the 2314/2319, 
each track contains four blocks with a 
maximum capacity of 1688 bytes. The number 
of programs (phases) and the size of each 
program to be contained in the core image 
library dictates the number of cylinders 
that must be allocated. Each program 
starts with a new block and only the last 
block of a program can contain less than 
1728 bytes of data for the 2311 or 1688 
bytes of data for the 2314/2319. 

Note : A phase is an overlay of a 
multiphase program or a complete program if 
not multiphase. 



Relocatable Library Directory 



This directory consists of one or more 
tracks, depending on the allocation 
specified by the user. It contains two 
types of information: 

1. System directory information for the 
relocatable directory and library. 
This information occupies the first 
five entries of the first record in 
the relocatable directory. 

2. An entry that describes each module in 
the relocatable library and contains: 

a. Module name 

b. Total number of text-record blocks 
required to contain this module 

c. Starting disk address of the first 
text-record of this module 

d. Change level identification. 
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NO. 




COMPONENT 


STARTING DISK ADDRESS 


NUMBER 
OF TRACKS 
(Allocation) 


R = REQUIRED 
0=OPTIONAL 




BB 


cc 


HH 


R 


1 


IPL Bootstrap Record 1 ($A$IPL1) 


00 


00 


00 


1 


1 


R 


IPL Bootstrap Record 2 ($A$IPLA) 


00 


00 


00 


2 


R 


Volume Label 


00 


00 


00 


3 


R 


User Volume Label 


00 


00 


00 


4 


O 


2 


System 
Directory 


Record 1 


00 


00 


01 


1 


1 


R 
R 
R 
R 


Record 2 


00 


00 


01 


2 


Record 3 


00 


00 


01 


3 


Record 4 


00 


00 


01 


4 


IPL Retrieval Program ($$A$IPL2) 


00 


00 


01 


5 


R 


3 


System Work Area (Librarian Area) 


00 


00 


02 




3 


R 


4 


Transient Directory (S$A and $$B Transients) 


00 


00 


05 






R 


5 


Open Directory ($$B0) 


00 


00 


06 






R 


6 


Library Routine Directory ($ Phasenames) 


00 


00 


07 






R 


7 


Foreground Program Directory (FGP) 


00 


00 


08 






R 


8 


Phase Directory (For Problem Program Phases) 


00 


00 


09 






R 


9 


Core Image Library Directory 


00 


01 for 2311 
00 for 231 4/ 
2319 


00 for 23 11 
10 for 231 4/ 
2319 




* 


R 


10 


Core Image Library 


00 


End of CI Directory 




* 


R 


X 


Y+l 


11 


Relocatable Library Directory 


00 


End of CI Library 




* 


O 


Z + l 


00 


12 


Relocatable Library 


00 


End of RL Directory 




* 


O 


X 


Y+l 


13 


Source Statement Library Directory 


00 


End of RL Library 




* 


O 


Z + l 


00 


14 


Source Statement Library 


00 


End of SS Directory 




* 


O 


X 


Y + l 


15 


Volume Area File Definition Storage Area 




End of SS Library 




2311:10 
2314/2319:20 


R 


Z + l 


00 


16 






End of Volume Area 




* 


O 






Z+2 


00 







*Allocation Dependent On User Requirements 
X = Ending CC of the Preceding Directory 
Y = Ending HH of the Preceding Directory 
Z = Ending CC of the Preceding Library 



Figure 1.1. System Residence Organization 
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Relocatable Library 



The relocatable library consists of five or 
more tracks, depending on the allocation 
specified by the user. The number of 
modules and the size of each module to be 
contained in this library dictates the 
number of tracks that must be allocated. 
Each allocated track contains 9 blocks 
(2311) or 16 blocks (2314/2319), and each 
block has a fixed length of 322 bytes. 
Each module starts with a new block but not 
necessarily a new track. 



the number of tracks that must be 
allocated. Each track contains 16 blocks 
(2311) or 27 blocks (2314/2319), and each 
block has a fixed length of 160 bytes. 
Each book starts with a new block but not 
necessarily a new track. Each book in the 
source statement library contains 
compressed card images of the source 
language input to the assembler or language 
translators. A compressed card image can 
overflow from one block to another. 



Label Information Cylinder 



source Statement Library Directory 



^This directory consists of one or more 
tracks, depending on the allocation 
specified by the user. It contains two 
types of information: 

1. system directory information for the 
source statement directory and 
library. This information occupies 
the first five entries of the first 
record in the source statement 
directory. 

2. An entry that describes each book (see 
Note 1) in the source statement 
library and contains: 

a. A sublibrary prefix: any 
alphameric character, $, #, or a, 
except A and C (see Note 2). 

b. Book name. 

c. Starting disk address of the first 
block of this book. 

d. Total number of blocks required to 
contain this book in the source 
statement library. 

e. Change level identification. 

Note 1 : A book is a sequence of source 
language statements, in compressed card 
image format, accessed by a single name. 

Note 2 : A and C are reserved for assembler 
and COBOL, respectively. 



Source Statement Library 



The source statement library consists of 
five or more tracks, depending on the 
allocation specified by the user. The 
number of books and the size of each book 
to be contained in this library dictates 



The label information cylinder (10 tracks 
| for 2311 or 20 tracks for 2314/2319) 
contains background and foreground user and 
standard label information. 



SUPVR Macro 



MULTIPROGRAMMING SUPPORT (MPS) 



Multiprogramming is the ability to run 
multiple programs concurrently, provision 
for which must be included in the DOS 
supervisor at system generation time. Each 
program resides in a different area of main 
storage called a partition. The three 
problem program partitions are designated 
background (BG) , foreground 1 (PI) , and 
foreground 2 (F2) . 

The background partition must be at 
least 10K because job control runs in the 
background partition and requires 10K bytes 
of main storage. However, 14K allows 
faster assemblies and linkage editing. 

The remaining main storage is divided 
between the two foreground partitions. To 
satisfy the requirements for the storage 
protect special feature, these partitions 
must begin and end on 2K boundaries. 
Because the MPS supervisor requires a 
minimum of 8K and the background partition 
requires a minimum of 10K, MPS will not 
function on systems with less than 24K of 
main storage (see Figure 1.2). 

MPS operates under the principle that in 
most commercial installations, the CPU is 
heavily I/O bound. Much of the CPU running 
time is spent waiting for a printer, a 
reader or a punch to complete a previous 
operation before the subsequent one can be 
started. With MPS, when a partition 
becomes I/O bound (that is, it cannot 
continue until the completion of some I/O 
operation) , a task selection routine in the 
MPS supervisor attempts to give CPU control 
to the next partition that is ready to run. 



( 
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SUPVR 



BO 



Supervisor Nucleus 1 




I/O Ta 






1 Patch Area j 


M Logical Transient Area ($$B) 1200 Bytes | 


Physical Transient Area ($$A) 552 Bytes 


CE 
. Table 


CE 
Area 


Background 8 Bytes (112 with Floating Point) ! 
Save Area MJ i 



Label Save I 
Area | 



Background Program Area 
10K Minimum 



F2 



IFl! 



j F2 Save Area (5)- 88 Bytes 
|(120 with Floating Point) 



T 

Label Save J 
Area (5) ! 



Foreground 2 Program Area 
Multiple of 2K 



I Fl Save Area(|)- 88 Bytes 
1(120 with Floating Point) 



Label Save j 
Area (3) i 



Foreground 1 Program Area 
Multiple of 2K 



\ 



The'se boundorf»$ 
j aremovabJe 



I (T) BG Save Area: 

Return PSW (8 Bytes) 



General Registers 9 through 
64 Bytes 



Length of Label Area (2 Bytes) 



Reserved (6 Bytes) 



Floating Point Registers 
32 Bytes 



CO FG Save Area: 

Program Name (8 Bytes) 
Return PSW (8 Bytes) 

General Registers 9 through 8 
64 Bytes 



Length of Label Area (2 Bytes) 



Reserved (6 Bytes) 



Floating Point Registers 
32 Bytes 



) 



Cy Length of the label area depends on the amount of storage specified by LBLTYP statement;! 
3 , For standard tope labels (any number) - 80 fcytes 

2. For sequential DASD and DTFPH MOUNT£D=SiNGLE - Bytes ! | 

3. For DTFIS, DTFDA ond DTFPH MOUNTEPr=ALL^ 84 Bytes plus 20 Bytes per extent ] 



Figure 1.2. MPS Storage Map 
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The partition to which control is given 
is determined by a priority system. Fl has 
highest priority followed by F2 and BG. A 
partition cannot be interrupted by one of 
lower priority. When an Fl program is 
ready to run, the task selection routine 
seizes control from a program of lower 
priority. One of the disadvantages in such 
an arrangement is the possibility of a high 
priority program never relinquishing 
control to other partitions. This can 
happen if the high priority program has few 
I/O requests . In general , the program with 
the largest number of I/O operations or 
wait time should reside in the highest 
priority partition. A compute (CPU) bound 
program should reside in a low priority 
partition (for example, BG) . 

Because the channel scheduler attempts 
to keep devices and channels busy 
asynchronously, it is an advantage for all 
programs to use sufficient I/O sceas to 
keep the channel queue stacked with 
requests. A lower priority partition is 
more likely to require multiple I/O areas 
to achieve this than is a higher priority 
partition . 



Partitioning 



Multiprogramming has been defined as a 
technique whereby two or more programs may 
operate concurrently, sharing system 
resources between them. The DOS 
multiprogramming support requires that such 
programs be co-resident in main storage. 
To achieve this, storage is divided into 3 
sections termed partitions (BG, Fl, and 
F2) . Each partition is capable of holding 
a distinct problem program. When a 
partition contains a program that is in 
course of execution, the partition is said 
to be active. When a partition does not 
contain such a program, or is not 
physically present in the system, then it 
is said to be inactive. 

Each partition is of fixed physical size 
and is defined by fixed boundaries. For 
this reason, DOS multiprogramming is termed 



fixed partition multiprogramming. 
Partition boundaries may be altered in any 
manner when all partitions are inactive 
(minimum background size is 10K) . When any 
partitions are active, boundaries can be 
altered only if the lower limit of each 
active partition is unchanged and the size 
of each active partition is not reduced. 

Each partition is allotted its own 
unique storage protection key; for this 
reason the size of any partition must be an 
integral multiple of 2K. Thus, a program 
contained in any one partition can read but 
not alter the contents of core locations 
contained in any other partition. 



Control Method 



Multiprogramming increases system 
efficiency by making better use of the 
available system resources than is possible 
in a single partition batched job 
environment. 

Multiprogramming support is written in 
such a way that the central processing unit 
does not enter the wait state if useful 
processing can be performed in any 
partition. Multiprogramming allows the 
input and output functions of one program 
to overlap with the processing functions of 
other programs . 



Task Selection 



A program yields control by issuing a 
supervisor call instruction to pass control 
to the supervisor routines. The SVC 
instruction contains a code that indicates 
its purpose. The most numerically 
significant of these codes in a 
multiprogramming context are those 
associated with input and output 
operations; therefore, only these codes are 
described. A complete list of DOS 
supervisor calls is given in Figure 1.3. 



i 
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Macro Supported 


SVC 


Function 


Dec. 


Hex. 


EXCP 








Execute channel programs. 


FETCH 


1 
2 
3 


1 
2 
3 


Fetch any phase . 

Fetch a logical transient (B- transient). 

Fetch or return from a physical transient (A -transient) . 


LOAD 


4 


4 


Load any phase . 


MVCOM 


5 


5 


Modify supervisor communications region. 


CANCEL 


6 


6 


Cancel a problem program or task. 


WAIT 


7 


7 


Wait for a CCB or TECB. 




8 


8 


Transfer control to the problem program from a logical transient (B -transient .) 


LBRET 


9 


9 


Return to a logical transient (B -transient) from the problem program after an 
SVC 8. 


SETIME 


10* 


A 


Set timer interval . 




11 
12 

13 


B 
C 

D 


Return from a logical transient (B -transient) . 

Logical AND (Reset) to second job control byte (displacement 57 in communi- 
cations region). 

Logical OR (Set) to second job control byte (displacement 57 in communications 
region) . 


EOJ 


14 


E 


Cancel job and go to job control for end of job step. 




15 


F 


Same as SVC except ignored if CHANQ table is full . (Primarily used by ERP.) 


STXIT (PC) 


16* 


10 


Provide supervisor with linkage to user's PC routine for program check interrupts. 


EXIT (PC) 


17* 


11 


Return from user's PC routine. 


STXIT (IT) 


18* 


12 


Provide supervisor with linkage to user's IT routine for interval timer interrupts. 


EXIT (IT) 


19* 


13 


Return from user's IT routine. 


STXIT (OC) 


20* 


14 


Provide supervisor with linkage to user's OC routine for external or attention 
interrupts (operator communications). 


EXIT (OC) 


21* 


15 


Return from user's OC routine. 




22* 
23* 


16 
17 


The first SVC 22 seizes the system for the issuing program by disabling multi- 
program operation. The second SVC 22 releases the system (enables multiprogram 
operation) . 
Load phase header. Phase load address is stored at user's address. 


SETIME 


24* 


18 


Provide supervisor with linkage to user's TECB and set timer interval . 




25* 

26* 
27* 


19 

1A 
IB 


Issue HALT I/O on a teleprocessing device, or HALT I/O on any device if issued 

by OLTEP. 

Validate address limits. 

Special HIO on teleprocessing devices. 



> 



* - optional 
Figure 1.3. Supervisor Calls (Part 1 of 2) 
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Macro Supported 


SVC 


Function 


Dec. 


Hex. 


EXIT (MR) 


28* 


1C 


Return from user's stacker select routine (MICR type devices only). 




29* 


ID 


Provide return from multiple wait macros WAITF and WAITM (except MICR type 
devices). 


QWAIT 


30* 


IE 


Wait for a QTAM element. 


QPOST 


31* 


IF 


Post a QTAM element. 




32 
33 
34 


20 
21 
22 


(Reserved) 

Reserved for internal macro COMRG . 

Reserved for internal macro GETIME. 


HOLD 


35* 


23 


Hold a track for use by the requesting task only. 


FREE 


36* 


24 


Free a track held by the task issuing the FREE . 


STXIT (AB) 


37* 


25 


Provide supervisor with linkage to user's AB routine for abnormal termination of 
a task . 


ATTACH 


38* 


26 


Initialize a subtask and establish its priority. 


DETACH 


39* 


27 


Perform normal termination of a subtask. It includes calling the FREE routine to 
free any tracks held by the subtask. 


POST 


40* 


28 


Inform the system of the termination of an event and ready any waiting tasks . 


DEQ 


41* 


29 


Inform the system that a previously enqueued resource is now available. 


ENQ 


42* 


2A 


Prevent tasks from simultaneous manipulation of a shared data area (resource). 




43* 

44* 

45* 

46* 

47* 

48 

49 

50 

51* 


2B 
2C 
2D 
2E 
2F 
30 
31 
32 
33 


Provide supervisor support for external creation and updating of SDR records. 

Provide supervisor support for external creation of OBR records. 

Provide emulator interface . 

Provide OLTEP with the facility to operate in supervisory state. 

Provide return from wait multiple WAITF for MICR type device. 

(Reserved) 

(Reserved) 

Reserved for LIOCS error recovery. 

Return phase length at OLTEP request. 



- optional 



Figure 1.3. Supervisor Calls (Part 2 of 2) 



i 
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SVC Code (EXCP) 

This code requests the supervisor to 
initiate an input or output operation. The 
address of a Command Control Block (CCB) 
located in the requesting program is also 
passed to the supervisor via register 1. 
This block contains information that 
describes the precise nature of the 
operation to be performed. 

When the supervisor receives the EXCP 
request but is unable to initiate the 
required operation, it places the request 
in a queue for later action. The traffic 
bit in the relevant CCB is then set to 
whether or not an operation can be started 
when requested. The supervisor then 
returns control to the program that 
requested the operation. 



When an input/output interrupt occurs, 
the supervisor identifies the operation in 
question and checks whether it has been 
satisfactorily performed. If it has, the 
traffic bit in the related CCB is set to 1; 
the owning partition is made ready to run, 
that is, if it was in a wait state it is 
removed from that state; and any further 
input/output operation pending for this 
channel or device is initiated. The task 
selection routine in the supervisor then 
gives control to the next partition of the 
highest system priority that is ready to 
run. 



The following three figures show the 
relationship between six different 
operations while operating under MPS. All 
three partitions are active. 



SVC Code 7 (WAIT) 

This code informs the supervisor that the 
program is unable to proceed further until 
a previously requested operation has been 
completed, and that the operation is still 
in progress because the relevant traffic 
bit is still set to 0. The program is 
placed in the wait state. Note that the 
instructions immediately preceding the 
supervisor call instruction form a test of 
the traffic bit so that, if the traffic bit 
is set to 1, the supervisor call is 
bypassed. When the SVC 7 is recognized, 
the program return address is reduced so 
that the instructions generated by the WAIT 
macro will be issued . 

When the supervisor recognizes an SVC 7 
interrupt, it records that the program is 
in the wait state. The supervisor then 
gives control to the next partition of the 
highest priority that is ready to run. If 
such a partition does not exist, the 
supervisor causes the central processing 
unit to enter the wait state until an 
interrupt occurs. 

A program loses control to the 
supervisor whenever an interrupt occurs. 
Only the input/output interrupts are 
described in the following text because 
they are the most significant interrupts in 
a multiprogramming environment. 



Figure 1. 1 assumes that programs were 
initiated at some prior point in time in 
all three partitions. The first part of 
Figure 1.4 shows that foreground 1 has 
control of the CPU and is processing. At 
some point in time, the program in Fl 
returns control of the CPU to the 
supervisor by issuing an I/O wait (SVC 7) . 

The supervisor goes through a task 
selection process, determines that 
foreground 2 is ready to run and gives CPU 
control to it. F2 processes its program 
until it requires I/O, and then returns 
control of the CPU to the supervisor by 
issuing an I/O wait (SVC 7). 

The supervisor goes through a task 
selection process, determines that Fl is 
not ready to run but the background is 
ready to run, and gives CPU control to the 
background. BG processes its program until 
it requires I/O and then returns control of 
the CPU to the supervisor by issuing an I/O 
wait (SVC 7) . 

The supervisor goes through a task 
selection process, determines that no 
partitions are ready to run, and gives 
control of the CPU to a task called All 
Bound. This task loads a PSW that puts the 
system in the wait state with all 
interrupts enabled. Note that no I/O 
interrupts have occurred. 
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f 

Foreground 1 (Fl) Processing 



Foreground 2 (F2) 



Background (BG) 



I/O Wait' 



Supervisor 



System in Wait State 



I/O Interrupts 



Waiting for I/O Completion 



Processing 
I/O Wait * 



Waiting for I/O Completion 



Processing 



Waiting for I/O Completion 



Task 
Selection 



Task 
Selection 



I/O Wait* 



Task 
Selection 



All 
Bound 



NOTES 



Inactive State 



Active State 



*l/0 Wait means an SVC 7 is issued (WAIT Macro) 



Figure 1.4. Processing and I/O Requests Relationship 
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Foreground 1 (Fl) 



Foreground 2 (F2) 



Background (BG) 



Supervisor 



System in Wait State 



I/O Interrupts 



1 2 



Waiting for I/O 



Waiting for I/O 



Waiting for I/O 



Waiting to be Selected 



Waiting to be Selected 



\ 



Posting Traffic Bit and Performing Task Selection 



All Bound 



I 

I 

Fl 



I 

I 

BG 



F2 



I/O INTERRUPT SEQUENCE 

1 . Fl 's I/O Interrupt Occurs 

2. BG's I/O Interrupt Occurs 

3. F2's I/O Interrupt Occurs 

Figure 1.5. First Example of Processing and I/O Requests with I/O Interrupts 



Figure 1.5 starts with all partitions 
waiting for I/O, and the system in the wait 
state with interrupts enabled. 

When the first I/O interrupt occurs, the 
supervisor I/O interrupt routine gets 
control of the CPU, and turns on the 
traffic bit in the CCB associated with the 
device causing the I/O interrupt (Fl 
partition) . The supervisor task selection 
routine then gets control, determines that 
Fl is through waiting, and gives CPU 
control to it. Fl starts processing its 
program. 

An I/O interrupt occurs and control 
passes to the supervisor I/O interrupt 
routine. It turns on the traffic bit in 
the CCB associated with the device causing 
the I/O interrupt (BG partition) . The 
supervisor task selection routine gets 
control, determines that Fl is still the 



highest priority program ready to run, and 
gives CPU control to it. Note that BG is 
still waiting, but now is ready to run 
because its I/O wait is complete. 



While Fl is processing, another I/O 
interrupt occurs and control passes to the 
supervisor I/O interrupt routine. It turns 
on the traffic bit in the CCB associated 
with the device causing the I/O interrupt 
(F2 partition) . The supervisor task 
selection routine then gets control of the 
CPU, determines that Fl is still the 
highest priority program that is ready to 
run, and gives CPU control to it. Note 
that both BG and F2 are now ready to run, 
but control of the CPU is retained by the 
highest priority partition (Fl) until it 
issues an SVC or until one of the four 
other system interrupts occurs. 
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2 3 



Foreground 1 (Fl) Waiting for I/O 



4 5 



Foreground 2 (F2) Waiting for I/O 



Background (BG) / Waiting for 



Supervisor 



System in Wait State 



6 7 

1 r 



Processing 



Processing 



I/O 



Processing 



" I 

I l 

I I 

I I 

Waiting to be Reselected 



Waiting to be Reselected 
H / 



l I 

I I 

I I 



\ 



t 



, / 



I Posting Traffic Bit and Performing Task Selection 

I 



All Bound 



I/O Interrupt 



I/O INTERRUPT SEQUENCE 

1 . BG's I/O Interrupt Occurs 

2. F2's I/O Interrupt Occurs 

3. Fl 's I/O Interrupt Occurs 



Figure 1.6. Second Example of Processing and I/O Requests with I/O Interrupts 



Figures 1.4 and 1.5 show a simplified 
version of what actually occurs. In actual 
practice, the process time for Fl would be 
longer than F2 or BG, and the sequence of 
I/O interrupts would probably be staggered. 

Figure 1.6 starts with all partitions 
waiting for I/O, and the system in the wait 
state with interrupts enabled. 

When the first I/O interrupt occurs, the 
supervisor I/O interrupt routine gets 
control of the CPU, and turns on the 
traffic bit in the CCB associated with the 
device causing the I/O interrupt (BG 
partition) . The supervisor task selection 
routine gets control, determines that the 
3G partition is the highest priority task 
ready to run, and gives CPU control to it. 
The BG partition starts processing with the 
instruction 6 bytes before the I/O wait 
(SVC 7). 



When the second I/O interrupt occurs, 
the supervisor I/O interrupt routine gets 
control of the CPU, and turns on the 
traffic bit in the CCB associated with the 
device causing the I/O interrupt (F2 
partition) . The supervisor task selection 
routine gets control of the CPU, determines 
that the F2 partition is now the highest 
priority partition ready to run, and gives 
CPU control to it. The F2 partition starts 
processing with the instruction 6 bytes 
before the I/O wait (SVC 7). 



when the third I/O interrupt occurs, the 
supervisor I/O interrupt routines gets 
control of the CPU, and turns on the 
traffic bit in the CCB associated with the 
device causing the I/O interrupt (Fl 
partition) . The supervisor task selection 
routine gets control of the CPU, determines 
that the Fl partition is now the highest 
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priority partition ready to run, and gives 
CPU control to it. 

The foreground 1 partition remains in 
control of the CPU until it issues an SVC 
or until one of the four other system 
interrupts occurs. 



System Considerations 



Any program that is process-bound 
(compute-bound) completely suppresses any 
event from taking place in any partition of 
lower priority, regardless of the 
utilization of channels and devices. Thus, 
if the program in the foreground 1 
partition is process-bound, 
multiprogramming cannot take place because 
a partition of lower priority cannot get 
control. In general, a foreground program 
should never be process-bound in a 
multiprogramming environment. 

Because the slowest devices are those 
that are associated with unit record 
equipment (e.g., card readers, card 
punches, line printers and terminals) , unit 
record and teleprocessing devices in a 
multiprogramming environment should be 
associated with the partitions of highest 
system priority. 

In general, the slowest input/output 
devices should run with maximum efficiency, 
because loss of efficiency on such devices 
is more serious in terms of system 
throughput than on faster devices. 

Note ; I/O bound programs with the slowest 
system devices should be allocated to the 
highest priority partitions. 

The efficiency of a low priority program 
depends on the quantity and frequency of 
processing time made available to it. The 
most advantageous high priority program (in 
terms of overall system efficiency) 
combines lengthy input and output 
operations with a minimum of processing. 

Every time an input/output interrupt 
occurs, it must be interrogated for all 
partitions of higher priority than the 
partition to which it relates. Therefore, 
a reduction in the number of such 
interrupts (which may be achieved by 
increasing blocking factors of tape and 
disk files) , promotes greater 
multiprogramming efficiency because it 
lowers system overhead. Increased blocking 
factors, however, result in increased core 
storage requirements. 



Another important system consideration 
is the use of two input or output areas in 
connection with one file (double 
buffering) . Double buffering increases 
computer utilization by allowing the 
overlap of input/output operations with 
processing. Multiprogramming has the same 
purpose. In double buffering, input/output 
operations are overlapped with processing 
relating to the same program; in 
multiprogramming, input/output operations 
are overlapped with processing relating to 
a different program. Therefore, the more 
efficiently double buffering operates in 
relation to a given foreground program, the 
less time will be freed for use by the 
background program. 

In a multiprogramming environment, it 
may prove more efficient in terms of total 
system throughput to dispense with double 
buffering for programs operating in 
foreground partitions. In most cases, main 
storage can be better applied to the 
accommodation of greater block sizes than 
to the accommodation of double input/output 
areas . 



Concurrent Peripheral Operation (CPO) 



The CPO (Concurrent Peripheral Operation) 
concept is the application of 
multiprogramming techniques to the basic 
utility operations of card-to-tape, 
tape-to-punch, tape-to-printer, and their 
disk equivalents. Such operations are 
performed in a separate storage partition. 

A typical CPO program is a file-to-file 
utility containing a minimum amount of 
processing. Blocking and deblocking 
operations and some data selection can be 
performed, but this is all. Thus, CPO fits 
the specifications for an efficient high 
priority program. A CPO program is 
normally associated with a unit record 
device and the greater part of its 
input/output time is likely to utilize 
subchannels of the multiplexor channel. 
Therefore, channel contention with other 
concurrent programs is greatly reduced. 
CPO is one of the most efficient practical 
applications of the multiprogramming 
technique . 



Operational Considerations 



Two methods used to initialize and operate 
programs in the foreground partitions are: 

1. Batch Job Foreground (BJF) : This 
method uses the job control program. 
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The foreground partition (s) 
essentially operates like the 
background part it ion (i.e., batched 
processing automatic job-to- job 
transition) . The foreground 
partition (s) must be a minimum of 10K. 

2. Single Program Initiator (SPI) : This 
method uses the IBM 1052 
Printer-Keyboard for System/360 or the 
IBM 3210 or 3215 Console 
Printer- Keyboards for System/370 to 
initialize single programs in the 
foreground partition (s) . When the 
single program is terminated (either 
under its own control by issuing an 
EOJ, DUMP or CANCEL macro, or through 
operator action, a program error or 
certain I/O failures), a terminating 
message is printed on the console and 
the foreground partition becomes 
inactive. To run the next single 
program in the foreground partition, 
the operator must again initialize it 
from the 1052, 3210, or 3215 console. 
The major advantage of SPI is that the 
foreground partition size can be a 
minimum of 2K bytes. 



Programming Considerations 



The output of the language compilers can be 
link-edited to run in any partition, 
provided enough core storage is available. 

In a system that supports both 
batched- job foreground and private core 
image libraries (see Private Core Image 
Libraries ) , the function of compiling can 
be run in the foreground partitions as well 
as the background partition, providing 
enough core storage is available in which 
to execute the compiler. The linkage 
editor can execute in any batched- job 
partition. A private core image library is 
required when executing the linkage editor 
in a foreground partition. 



System Generation Guidelines 



The multiprogramming facility is specified 

at system generation time by the 

MPS= keyword parameter in the SOPVR macro. 



JNO | 
MPS=< YES > 

(bjf) 



any and all multiple partition 
operation. NO is the assumed 
value . 

YES When yes is specified, one, two, 
or three problem program 
partitions may exist. The 
foreground partitions may only be 
initialized using the single 
program initiator (SPI). 

BJF Under this option, one, two, or 
three problem program partitions 
may exist and the foreground 
partition (s) may be controlled 
either by job control or the 
single program initiator (SPI). 

The parameter YES or BJF must be 
specified if the supervisor is to be 
generated to support QTAM. 



AMERICAN NATIONAL STANDARD CODE FOR 
INFORMATION INTERCHANGE (ASCII) SUPPORT 



In addition to processing EBCDIC data 
files, DOS can process magnetic tape files 
written in ASCII (American National 
Standard Code for Information Interchange) , 
a 128-character, 7-bit code. The 
high-order bit in the System/360 8-bit 
environment is zero. ASCII tape files may 
be either unlabeled or labeled according to 
the specifications of the American National 
Standards Institute, Inc. (ANSI). 



NO This option automatically creates 
a background partition consisting 
of all available main storage 
above the supervisor and negates 



System Considerations 



ASCII tape files may be processed in either 
a foreground or background partition. 
Because internal processing of ASCII files 
is performed in EBCDIC, the data is 
translated at I/O time. Input files 
containing ASCII data are translated to 
EBCDIC as soon as the record is read into 
the I/O area. Output files described as 
ASCII are translated from EBCDIC to ASCII 
just prior to writing the record . 

Two translate tables (providing for the 
conversion from ASCII to EBCDIC and from 
EBCDIC to ASCII) are generated at system 
generation time by specifying the ASCII=YES 
parameter in the SUPVR macro. These tables 
are located immediately before the Seek 
Address Blocks in the supervisor. The 
address of the ASCII-EBCDIC translate table 
is in locations HH-M (decimal) of the 
communications region extension. Add 256 
(decimal) to this table to get the address 
of the EBCDIC-ASCII translate table. The 
address of the communications region 
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extension is in bytes 136-139 (decimal) of 
the communications region. Figures 1.7 and 
1 . 8 show the system and background 
communications regions. 



System Generation Guidelines 



To generate supervisor support for handling 
ASCII tape files, ASCII=YES must be 
specified in the SUPVR macro. 



NO 



YES 



ascii=\yesj 



When ASCII=NO is specified, or if 
the parameter is omitted or 
incorrectly specified, the 
translate tables are not 
generated. The system will then 
process EBCDIC files only. 



When YES is specified, the two 
translate tables are generated in 
the supervisor. The address of 
the first table (ASCII-EBCDIC) is 
inserted in each communication 
region extension to enable 
accessibility by any task in any 
partition. 
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COMREG* 

Displacement 
hexadecimal 

Displacement 
decimal 



Displacement 
hexadecimal 

Displacement 
decimal 



Displacement 
hexadecimal 

Displacement 
decimal 



Displacement 
hexadecimal 

Displacement 
decimal 



Displacement 
hexadecimal 

Displacement 
decimal 







8 
8 


OA 
10 


OC 
12 


17 
23 


18 
24 


20 
32 


24 
36 


28 
40 


2C 

44 


Date 


Address of 
PPBEG 


Address of 
EOSSP 


Problem Program Use 


UPSI 
Byte 


Job Name 


Highest 
Storage 
Address 
of the 
Partition 


End Address 
of Last Phase 
Fetched or 
Loaded 


Address of 
Uppermost 
Byte of Phase 
with Highest 
Ending Address 


Label 
Area 
Length 


XXXXXXXX 


XX 


XX 


XXXXXXXXXXX 


X 


XXXXXXXX 


XXXX 


XXXX 


XXXX 


XX 



2E 
46 


30 
48 


34 
52 


35 
53 


36 

54 


37 

55 


38 
56 


39 
57 


3A 
58 


3B 
59 


3C 
60 


3E 
62 


PIK 

(PID) 


End of 

Storage 

Address 


Machine 

Confg. 

Byte 


System 
Confg. 
Byte 


Standard 

Language 

Translator 

I/O 

Options 


Dump, 
Log and 
ASCII 
Options 


Job 

Control 

Byte 


Linkage 
Control 
Byte 


Language 
Translator 
Control 
Byte 


Job 

Duration 
Indicator 
Byte 


Disk 

Address of 
Label 
Cylinder 


Address 

of 

FOCL 


XX 


XXXX 


X 


X 


X 


X 


X 


X 


X 


X 


XX 


XX 



Job Control Switches 



40 


42 


44 


46 


48 


4A 


4C 


4E 


4F 


58 


5A 


5C 


64 


66 


68 


70 


72 


74 


76 


78 


79 


88 


90 


92 


Address 


Address 


Address 


Address 


Address 


Address 


Address 


Line 


System Date 


LIOCS 


Address of 


ID Number 


of 


of 


of 


of 


of 


of 


of 


Count 




Comm. 


1st Part of 


of Last 


PUB 


FAVP 


JIB 


TEB 


FICL 


NICL 


LUB 


for 
SYSLST 




Bytes 


PIB Table 


Checkpoint 


XX 


XX 


XX 


XX 


XX 


XX 


XX 


X 


xxxxxxxxx 


XX 


XX 


XX 



5E 


60 


62 


64 


66 


68 


6A 


6C 


6E 


94 


96 


98 


100 


102 


104 


106 


108 


110 


Length of LUB 
ID Queue = 
No. of Channel 
Queue Entries 


Address of 
Disk 

Information 
Block (DIB) 


Address of 
Error 
Recovery 
Block 


Address of 
PC Option 
Table less 
8 bytes 


Address of 
IT Option 
Table less 
8 bytes 


Address of 
OC Option 
Table less 
8 bytes 


Key of 
Program 
with Timer 
Support 


Address of 
the LUBID 
Queue 


Logical 

Transient 

Key 


XX 


XX 


XX 


XX 


XX 


XX 


XX 


XX 


XX 



70 
112 


7C 
124 


7E 
126 


80 
128 


84 
132 


86 
134 


87 
135 


88 
136 


Supervisor Constants 


Address of 
2nd 
Part of 
PIB Table 


Address of 
MICR DTF 
Table 
(PDTABB) 


Address of 
QTAM 
Vector 
Table 


Address of 
BG Comm. 
Region 


Op- 
tion 
Indi- 
cator 


System 
Config 
uration 
Byte 2 


Pointer to 
Comm. 
Region 
Extension 


XXXXXXXXXXXX 


XX 


XX 


XXXX 


XX 


X 


X 


XXXX 



* The address of the communications region is in fixed location X'14' - X'17'. 

Displacement values illustrated can be used to access the listing and/or the key that follows the figure. 
The key offers more detailed information about each area when necessary. 

Figure 1.7. System Communications Region (Part 1 of 5) 
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Key to Communications Region Displacements: 



LU 

on 



24 



32 



36 



40 



44 



46 



MM/DD/YY or DD/MM/YY obtained from the job control date statement. Format controlled by COMREG + 53 
(System Configuration Byte, date convention bit 0). 

Address of the problem program area. 

Address of the beginning of the problem program area. Y (EOSSP) = Y (PPBEG) if the storage protection option has not 
been selected. Y (EOSSP) equals the first main storage location with a storage protection key of 1 , if storage protection 
is supported. 

User area. If seek separation option is specified, bytes 12 and 13 are used at IPL lime for the address of the seek 
address block. 

User program switch indicator. 

Job name set by the job control program from information found in the job statement. 

Address of the uppermost byte of the problem program area as determined by the IPL program (Clear storage routine 
determines the address, ENDRD routine of $$A$IPL2 stores it.), or the address of the uppermost byte of the partition 
as determined during processing of the ALLOC statement. 

Address of the uppermost byte of the last phase of the problem program fetched or loaded. The initial value (as shown) 
is overlaid by the first fetch or load to the problem program area. 

Highest ending main-storage address of the phase among all the phases having the same first four characters as the 
operand on the EXEC statement. For the background partition only, job control builds a phase directory of these 
phases. The address value may be incorrect if the program loads any of these phases above its link-edited origin 
address. If the EXEC statement has no operand, job control places in this location the ending address of the program 
just link-edited. 

Length of the problem program label area. 

Program Interrupt Key - PIK (if asynchronous processing is not supported): Value is equal to the displacement from the 
start of the PIB table to the PIB for the task. 

OR 
Partition Identifier- PID (if asynchronous processing is supported): Value is hex 10, 20, or 30 to identify the partition 
in which a maintaskora subtask is running. (See the communications region extension, displacement 18, for the PIK 
in an asynchronous processing supervisor.) 

First byte - always zero. 

Second byte - contains the key of the program that was last enabled for interrupts, or the partition identifier in 
an AP supervisor. 





Task 






PIK (PID) Value 




*AII Bound 






X'00' 




BG 






X'10' 




*F2 






X'20' 




*F1 






X'30 1 




Attn Rtn 






X'40' 




Quiesce I/O 






X'50' 




Supervisor 






X'60' 




*These tasks do 
Logical end of main 


not exis 
storage 


in a non-MPS supervisor 


48 


address. 



) 



Figure 1.7. System Communications Region (Part 2 of 5) 
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<ey to Communications Region Displacements: 








Machine 
BitO 


Configuration Byte (Values set at supervisor generation time.) 
1 = Storage protect feature 






52 










= No storage protect feature 






1 


1 = Decimal feature 








= No decimal feature 






2 


1 = Floating-point feature 
= No floating-point feature 






3 


1 = Physical transient overlap option 
= No physical transient overlap option 






4 


1 = Timer feature 
= No timer feature 






5 


1 = Channel switching device 
= No channel switching device 






6 


1 = Burst mode on multiplex channel support 
= No burst mode on multiplex channel support 








7: Reserved 

System Configuration Byte 

BitO: 1 = DDMMYY 1 m . .. ... , , .. .. , r Tnir , 

n - MMnnvv I (Date convention bit set at generation time by brUJCJ 






53 








1 


1 = Multiprogramming environment 








= Batch job environment 






2 


1 = DASD file-protect supported 

= No file-protect support for DASD 






3 


1 = DASD SYSIN - SYSOUT 
= No DASD SYSIN - SYSOUT 






4 


1 = Teleprocessing 
= No teleprocessing 






5 


1 = Batch job in foreground 
= No BJF 






6 


1 = Asynchronous processing 
= No AP 






7 


1 = Track Hold 








This byte 
BitO 


= No Track Hold 
contains the standard language translator I/O options (set by the STDJC macro). 
DECK option 1 = yes, output object modules on SYSPCH 






54 








1 


LIST option 1 = yes, output source module listings and diagnostics on SYSLST 






2 


LISTX option 1 = yes, output hexadecimal object module listings on SYSLST (compilers only) 




3 


SYM option 1 = yes, output symbol tables on SYSLST/SYSPCH 






4 


XREF option 1 = yes, output symbolic cross reference list on SYSLST 






5 


ERRS option 1 = yes, output diagnostics on SYSLST (compilers only) 






6 


CHARSET option 1 = 48, input on SYSIPT is 48 or 60 character set 








7 

This byte 
for the pr 


Reserved 

contains the standard supervisor options for abnormal EOJ and control statement display, 
ssence of the ASCII-EBCDIC and EBCDIC- ASCII translation tables. 


and the indicator 




55 








BitO 
1 


Always on 

DUMP option 1 = yes, dump registers and storage on SYSLST 






2 


Reserved 






3 


LOG option 1 = yes, list all control statements on SYSLST 






4-6 


Reserved 






. 7 


ASCII option 1 = yes, ASCII supported 





Figure 1.7. System Communications Region (Part 3 of 5) 



< 



32 DOS System Programmer's Guide 



Key to Communications Region Displacement: 



s 



H 



58 



59 



Job control byte 

Bit 0: 1 = Job Accounting 

Interface (JA) not supported 

= Job Accounting 

Interface (JA) is supported 
1 : 1 = Return to caller on LIOCS disk open failure 

= Do not return to caller on LIOCS disk open failure 
2: 1 = Job control input from SYSRDR 

= Job control input from SYSLOG 
3: 1 = Job control output on SYSLOG 

= Job control output not on SYSLOG 
4: 1 = Cancel job 

= Do not cancel job 
5: 1 = Pause at end-of-job step 

= No pause at end-of-job step 
6: 1 = SYSLOG is not a 1052 

= SYSLOG is a 1052 
7: 1 = SYSLOG is assigned to the same device as SYSLST 

= SYSLOG is not assigned to the same device as SYSLST 

Linkage control byte 

Bit 0: 1 = SYSLNK open for output 

= SYSLN K not open for output 
1 : 1 = $ or FG program phase deleted, renamed, or cataloged (flag bit for $MAINEOJ) 
2: 1 = Allow EXEC 

= Suppress EXEC 
3: 1 = Catalog linkage editor output 

= Do not catalog linkage editor output 
4: 1 = Supervisor has been updated 

= Supervisor has not been updated 
5: 1 = Executing in AUTOTEST mode 

= Not executing in AUTOTEST mode 
6: 1 = Reallocate or condense in progress 
7: 1 = Fetch $MAINEOJ at end of job to update system directory 

= Do not fetch $MAINEOJ at end of job for update 

Language processor control byte. This is a set of switches used to specify nonstandard language translator options. 
The switches within the byte are controlled by job control OPTION statements and when set to 1 , override standard 
options. The format of this byte is identical to the stnadard option byte (displacement 54) with one exception: 
Bit 7 in this byte is used to indicate to LIOCS that the rewind and unload option has been specified. 

Job duration indicator byte 

Bit 0: 1 = Within a job condition 

= Outside a job condition 
1 : 1 = Dump on an abnormal end-of-job condition 

= No dump on abnormal EOJ 
2: 1 = Pause at EOJ step 

= No pause at EOJ 
3: 1 = Job control output on SYSLST 

= Output not on SYSLST 
4: 1 = Job is being run out of sequence with a temporary assignment for SYSRDR 

= Conditions for 1 setting not met 
5: 1 = PCI L is being condensed 

= PCIL is not being condensed 
6: Reserved 
7: 1 = Batch command just issued 

= Condition for 1 setting did not occur 



> Set by Attention Routine for Job Control 



Figure 1.7. System Communications Region (Part 1 of 5) 
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Key to Communications Region Displacements: 



Binary disk address of the volume label area (label cylinder). 



GEHZl 



As illustrated (Figures for information blocks, I/O tables, and pointers 
begin at Figure 1 .14 which refers to more detailed Figures). 



H 
H 



90 



H 



Set to the value nn specified in the LINES = nn parameter of the STDJC macro. 

The format of the system date contained within this field is determined by the I PL program from information supplied 
in the date convention byte (displacement 53). Bytes 85-87 contain the day count. 

Bytes reserved for use by LIOCS. Transient dump programs insert a key to indicate to the LIOCS end-of-volume 
routine, $$BCMT07, that it was called by a B-transient. 

Address of the first part of the program information block (PIB) table. (See Figures 4.4, and 4.5.) 

ID number of the last checkpoint. Temporary indicator of file protected DASD. Used at IPL time, when 
DASDFP is specified. 

Length of the LUBID queue (in bytes). This equals the number of channel queue entries. It can also be used to 
access the REQID, LUBDSP, and TKREQID queues: (See Figure 1 .29.) 

Address of disk I/O position data. This is the starting address of the disk information block (DIB)table (See Figure 1 .24). 

Address of the beginning of the error recovery block. The error recovery block contains addresses of error recovery 
exits, error recovery queue information that can be used by physical transients routines, and defines storage for the 
error queue entries 

1 100 {— »» |"ll04~j As illustrated (See Figure 1 .13). 

Key of the program (BG, F2, or Fl) that has timer support. 

As illustrated (See Figure 1 .29). 



94 



H 



98 



108 



110 



112 



124 



126 



128 



132 



134 



135 



136 



Logical Transient Key (LTK) contains the same value as the PIK (PID) (Displacement 46) when the logical transient is 
requested. When the transient area is not in use, LTK is equal to zero. The SVC 2 routine sets the LTK. The 
SVC 11 routine resets the LTK. 

Supervisor constants: 

DOLLARBO (4 bytes) = C'$$BO' 

SSKADR (5 bytes) = XL5'0' 

LTAREA (3 bytes) = Adcon of LTSVPT, logical transient save pointer 

Address of second part of program information block (PIB) table (See Figure 4.6). 

Address of PDTABB, table of DTF addresses for MICR support (See Figure 1 .9). 

Address of QTAM vector table (IJLQTTAD). 

Address of background communications region. 

Option Indicator Byte 

Bit 0: 1 = MCRR indicated for OBR writer 

= No MCRR indicated for OBR writer 
1: 1 = EU interface active 

= EU interface not active 
2: 1 = Teleprocessing request 

= No teleprocessing request 
3: 1 = Supervisor support for only 9-track tape 

= Supervisor does not support 9-track tape exclusively 
4: Reserved 
5: 1 = RETAIN/370 support generated 

= RETAIN/370 support not generated 
6- 7: Reserved 

System Configuration Byte 2 

Bit 0: 1 = PCIL supported 

= PCIL not supported 
1 -7: Reserved 

Pointer to communications region extension (See Figure 1 .8). 



Figure 1.7. System Communications Region (Part 5 of 5) 
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BGXTNSN (See Note) 



(Hexadecimal 
Displacement) 

(Decimal 

Displacement) 


4 
4 


8 
8 


oc 

12 


10 
16 


12 
18 


14 
20 


18 

24 


1C 
28 


20 
32 


CE Table 
Address 


Track Hold 
Table Address 
(THTABAD) 


Difference 
Between 1st 
and 2nd Part 
of PIB Table 
(PIBDtFF) 


AB Termin- 
ation Table 
Address -8 
(ABPTR) 


ID of 

Task 

Owning 

LTA 

(LID) 


ID of 
Task 
Running 
(PIK) 


Task Re- 
quester ID 
Table Address 
(TKIDPTR) 


Address 
Used by 
QTAM 
(MVCFLD) 


SDR 

Communications 
Address 
(SDRTABLE) 


TEBV 
Table 
Address 
(TEBVTAB) 


XXXX 


XXXX 


XXXX 


XXXX 


XX 




XX 


XXXX 


XXXX 


XXXX 


XXXX 



24 (Hexadecimal 


28 


2C 


30 


34 


38 


3C 


Displacement) 














36 (Decimal 


40 


44 


48 


52 


56 


60 


Displacement) 














OLTEP 


RMS 


ASCII-EBCDIC 




JAI Common 


JAI Partition 


&SYSPARM 


Linkage 


Linkage 


Translation 


(Reserved) 


Table Address 


Table Address 


Field 


Address 


Address 
(RASLINK) 


Table Address 




(ACCTCOMN) 


(ACCTxx) 


Address 


XXXX 


XXXX 


XXXX 


XXXX 


XXXX 


XXXX 


XXXX 



Key to displacements : 

CE Table Address. 

| 4 | Track Hold Table Address (THTABAD). 

I 8 I Difference between addresses of first part of PIB table and second part of PIB table (PIBDIFF). 

12 I Abnormal Termination Table Address (minus 8) (ABPTR). 

I 16 I Identification (LID) of the task owning the Logical Transient Area. Contains same value as PIK (displacement 18) when LTA is in use. 
Contains zero when LTA is not in use. 

I 18 I Program Interrupt Key (PIK) if asynchronous processing is supported. Value is equal to the displacement of the start of the PIB table 

' ' to the PIB of the main task or subtask being selected (running). 

First byte - zero 

Second byte - contains the displacement into the PIB table for a maintask or a subtask. 
Maintask - PIK value is hex 10, 20, or 30. 
Subtask - PIK value is hex 70, 80, 90, . . . F0. 



20 



24 



28 



32 



36 



40 



44 



48 



52 



56 



60 



Task Requester ID Table Address (TKIDPTR). 

MVCFLD address used by QTAM. 

Statistical Data Recorder Table Address (SDRTABLE). 

Tape Error Blocks by Volume Table Address (TEBVTAB). 

Pointer to OLTEP Linkage Addresses 

RMS Linkage Area Address (RASLINK) 

ASCII-EBCDIC Translation Table Address. 

(Reserved) 

JAI Common Table Address (ACCTCOMN) 

JAI Partition Table Address (ACCTxx; where xx = BG, F2, or Fl). 

Address of &SYSPARM Field. 



Note : If communications regions are generated for the foreground partitions, the labels in those extensions will be F2XTNSN 
and F1XTNSN. The extensions, wherever used, are generated by the COMMNEX macro. Following the background 
extension (and immediately preceding the MCRR Linkage Table) is a six-byte area. The first four bytes are the address of 
the background save area (BGSAV), and the last two bytes are the value 4,096, used to restore base registers. 



Figure 1.8 Background Communications Region Extension (BGXTNSN) 
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MAGNETIC INK CHARACTER RECOGNITION SUPPORT 
(MICR) 



A Magnetic Character Reader, such as an IBM 
| 1255, 1259, 1412, or 1419, can be attached 
to a channel for reading 

magnetically-inscribed data on checks and 
other banking documents. They differ 
mainly in document reading rates. The 1255 
reads at speeds as high as 500 
six- inch-long documents per minute on its 
Model 1, and 750 documents per minute on 
its Models 2 and 3; the 1259 reads at 
speeds as high as 600 six- inch- long 
documents per minute; the 1412, at speeds 
as high as 950 documents per minute; the 
1419, at speeds as high as 1,600 per 
minute. Specific speeds depend on document 
length as well as on the program. 



System Considerations 



The DOS supervisor support allows operation 
of Magnetic Ink Character Recognition 
(MICR) devices in either a foreground or 
background area. An extension to the DOS 
supervisor monitors, by means of external 
interrupts, the reading of documents into a 
user- supplied I/O area (document buffer 
area) . All MICR documents must be accessed 
through logical IOCS. Logical IOCS gives 
you the next sequential document and 
automatically engages and disengages the 
devices, as necessary, to provide a 
continuous stream of input. Detected error 
conditions and information are passed to 
you in each document buffer. 

The magnetic character readers are 
unique in that documents must be read at a 
rate dictated by the device rather than by 
the program. To ensure time for necessary 
processing (including determination of 
pocket selection) a MICR device generates 
an external interrupt at read completion of 
each MICR document. The supervisor gives 
highest priority to external interrupt 
processing. 

In an MPS system with MICR document 
processing, any partition (background or 
foreground) can use MICR devices. For 
programs with one MICR device, GET macro 



instructions are provided. For multiple 
MICR processing, READ, CHECK, and WAITF 
macro instructions allow processing to 
continue as long as one of the files has 
documents ready for processing. Figure 1.9 
shows the tables for MICR DTF addresses and 
pointers. 



System Generation Guidelines 



To specify supervisor support for MICR 
devices, the MICR= parameter must be 
included in the SUPVR macro. 

1. If both 1412s and 1419s are present, 
specify MICR=1419. If 1255s or 1259s 
are to be supported, also specify 
MICR=1419. MICR=1419D indicates Dual 
Address Adapter 1419s. 

2. 1419 support gives 1255/1259/1270/1275 
capability. The 1270/1275 are optical 
reader/ sorters . 



I 3 



If 1255/1259/1270/1275/1412/1419S are 
attached to the multiplexor channel, 
the PIOCS parameter BMPX=YES is not 
supported. 

If MICR support is required on a Model 
65, specify MODEL=65 in the CONFG 
macro. 



5. For MICR support on selector channel, 
specify MRSLCH=YES in the PIOCS macro. 

MICR processing requires at least two I/O 
channels. If MICR devices are attached to 
the multiplexor channel, no burst mode 
devices are supported on the multiplexor 
channel. MICRs should be attached as the 
highest priority devices on the multiplexor 
channel. Single addressing 1412s or 1419s 
are supported on any selector channel, but 
device performance is maintained only if a 
selector channel is dedicated to a single 
MICR device. Also note that the Dual 
Address 1419 is not attachable to selector 
channels . 

In addition, MICR processing requires 
either the direct control feature or the 
external interrupt feature. 
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The table of DTF addresses (PDTABB) contains six 8- byte entries; one for each external line of the 
direct control feature on the system. 



PDTABB 



Byte' 



16 
24 
32 
40 



-+■ 



Nl 



PDSTAT + 1 



X'FE' 



Nl PDSTAT + 1 



X'FD' 



Nl 



PDSTAT + 1 



X'FB' 



Nl 



PDSTAT + 1 



X'F7' 



Nl 



PDSTAT + 1 



X'EF' 



Nl 



PDSTAT + 1 



X'DF' 



o n 



DTF address for MICR: 
Device on line 7 



Device on line 6 



Device on line 5 



Device on line 4 



Device on line 3 



Device on line 2 



Background = 10 
Foreground 2 = 20 
Foreground 1 = 30 



• Bytes 0-3 — Contain an 'AND' instruction that is executed in main line coding to turn off the 
external line status after its detection. 



PDSTAT + 1 contains one or more of the following interrupt codes: 



PSW Interrupt 


Interrupt Code 


External 


Code Bit 


(PSW Bits 26- 


31)* 


Interrupt Cause 


31 


nnnnnnnl 




External signal 7 


30 


nnnnnnln 




External signal 6 


29 


nnnnnlnn 




External signal 5 


28 


nnnnlnnn 




External signal 4 


27 


nnnlnnnn 




External signal 3 


26 


nnlnnnnn 




External signal 2 



• Byte 4- - Contains the flag of the partition containing the DTF. 

• Bytes 5-7 - - Contain the address of the DTF table. 



Table of pointers (PDTABA) to DTF addresses associated with the external interrupt line. The table 
contains the status in descending order from Bit 31 to Bit 26 of the external old PSW. 



PDTABA 



Byte 



16 
24 
32 
40 
48 
56 





1 1 

00 


1 

08 


1 

00 


1 

10 


H 

00 


1 1 

08 


1 1 

00 


18 




00 


08 


00 


10 


00 


08 


00 


20 




00 


08 


00 


10 


00 


08 


00 


18 




00 


08 


00 


10 


00 


08 


00 


28 




00 


08 


00 


10 


00 


08 


00 


18 




00 


08 


00 


10 


00 


08 


00 


20 




00 


08 


00 


10 


00 


08 


00 


18 




00 


08 


00 


10 


00 


08 


00 | 





*n=other external - interrupt conditions. 

Bytes 126 and 127 (X'7E'- '7F') of the communications region contain the address of these 
tables. Label PDTABB identifies the first byte of the first table. 

Figure 1.9. Tables for MICR DTF Addresses and Pointers 
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ASYNCHRONOUS PROCESSING (AP) 



The asynchronous processing function, also 
known as multitasking, provides greater use 
of system resources at the partition level. 
Multitasking provides the ability to 
execute more than one program in a 
partition, that is, the ability to do 
multiprogramming within a partition (or in 
all three partitions) of the DOS system. 
Just as multiprogramming between partitions 
can increase the system throughput, 
multitasking can increase overlap of I/O 
activity and computer processing for a 
given job. 



To perform multiprogramming within a 
partition, the program must consist of a 
main program (main task) and one or more 
subprograms (subtasks) . 

Because multitasking is a logical 
extension of the current task selection 
mechanism, a maximum of nine subtasks can 
exist in the system at any given time. 
These nine subtasks can all reside in one 
partition, or can be spread among the three 
available partitions. A total of 12 tasks 
(a task can be considered either a main 
task or a subtask) can be executed 
concurrently in the system. 

The subtasks share the same partition 
with their associated main task. The main 
task initiates (attaches) execution of the 
subtasks. The ability of the main task to 
attach subtasks minimizes operator 
intervention. Storage within the partition 
may be allocated to the main task and its 
associated subtasks in any way desired by 
the user. Subtasks have the same storage 
protect key as the main task. 

When subtasks are attached to a given 
partition, they retain the priority of that 
partition. Priorities are also established 
within the partitions. The priority within 
a partition is determined by the order in 
which a subtask is initiated. The first 
subtask to be attached has the highest 
priority, and as each subsequent subtask is 
attached, it has the next highest priority, 
followed by the main task which has the 
lowest priority. When a subtask is 
attached, it receives control from the 
system before control is returned to the 
main task. See Figure 1.10 for an example 
describing priority structure in a 
multitasking environment. If the Fl 
partition has two attached subtasks, the F2 
partition has four attached subtasks, and 
the BG partition has three attached 
subtasks (a maximum of nine subtasks), 
their priority would be as shown (with 1 
being the highest priority and 12 the 
lowest priority) . 



A subtask can operate independently of 
its main task and has its own save area for 
registers. The subtask can communicate 
with other subtasks and main task via a set 
of macro instructions (see Intertask 
Communication) . 



Partition 



Fl 



Subtask 1 
Subtask 2 
Main Task 



Priority 



F2 Subtask 1 
Subtask 2 
Subtask 3 
Subtask 4 
Main task 

BG Subtask 1 
Subtask 2 
Subtask 3 
Main Task 



9 
10 
11 
12 



H 



Figure 1.10. 



Example of Multitasking 
Priorities 



it 



When a subtask is no longer required, 
can be detached from the system. The 
subtask can either detach itself or be 
detached by its main task. When one or 
more subtasks are detached, subtasks with 
lower priorities receive the next highest 
priority. If a detached subtask is later 
attached, it becomes the lowest priority 
subtask in the partition, but it still has 
higher priority than the main task. 



System Considerations 



Under DOS there are additional optional 
components and specifications that greatly 
enhance multitasking operations. 

Track Hold ; The track hold facility 
prevents two independent subroutines in the 
same partition or in two different 
partitions from simultaneously trying to 
update the same record or write a new 
record on the same track when processing 
DTFDA, DTFIS, and DTFSD files. When this 
facility is used, a second routine 
requesting an I/O operation on a track 
being held must wait for that track to be 
freed by the first routine. Because track 
hold is implemented by programming rather 
than hardware, all routines processing the 
same DASD files must use this facility to 
ensure proper protection. This facility 
can be used without specifying AP=YES and 
is specified at system generation time. 
See discussion of TRKHLD parameter under 
FOPT Macro for more information. 
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Multiple Wait. ; Under DOS, a number of 
independent logical IOCS operations 
(requiring explicit waiting for completion) 
can be initiated before waiting for the 
completion of any particular operation. 
Once all logical IOCS operations have been 
initiated, you must determine the sequence 
in which you will wait for their 
completion. Once you wait for a particular 
operation, you no longer have control, even 
though one of the remaining operations 
completes before the one on which the wait 
occurs and useful processing could have 
been done. This can be avoided at the 
physical IOCS level, but requires some 
additional coding effort on your part. 

The multiple wait facility allows you to 
wait asynchronously for any one of a number 
of I/O operations to complete at either the 
logical or physical IOCS level for the 
above situation. This facility provides 
increased I/O overlap processing and is 
specified at system generation time. See 
discussion of WAITM parameter under FOPT 
Macro for more information. 



the same device type DTFs in a multitasking 
environment. For example, one PRMOD can 
support several subtasks using multiple 
printers within a partition. One DAMOD can 
support several subtasks within a 
partition. 



Multitasking Macro Usage 



Although these four functions (asynchronous 
processing, track hold, multiple wait and 
abnormal termination) can be used 
independently, they are discussed under the 
heading where they are most frequently 
used. The multitasking macros are designed 
to handle three basic situations: subtask 
initiation and normal termination,, 
resource protection and intertask 
communication. See Supervisor and I/O 
Macros listed in the Preface for a 
description of the macro formats. Some 
examples using the multitasking macros are 
included. 



Abnormal Termination : Under DOS, your 
program is canceled when certain error 
conditions occur. In many cases, it is 
desirable to perform certain termination 
functions (e.g., close files) to minimize 
any problems that may occur. The abnormal 
termination facility allows for these 
situations via a user exit. This function 
is specified at system generation time and 
implemented via the AB operand of the STXIT 
macro. 



Subtask Initiation and Normal Termination 



Subtask initiation can only be performed by 
a main task that issues an ATTACH macro 
instruction. Normal subtask termination 
can be performed by either a main task or a 
subtask that issues a DETACH macro 
instruction. 



When the supervisor determines that the 
task has been abnormally terminated, 
control passes to the task's abnormal 
termination routine. In this routine, you 
may close data files (such as an indexed 
sequential ADD) or perform other operations 
that are necessary to minimize any possible 
damage. Abnormal termination exits can be 
established for both main tasks and 
subtasks or, if desired, subtasks can share 
the coding of their main task's abnormal 
termination routine. It is strongly 
suggested that in the shared abnormal 
termination routine no I/O be performed. 
If I/O is attempted and causes cancelation, 
all tasks in the partition are canceled. 
Any abnormal termination within the 
abnormal termination routine causes the 
task (or job if in the main task) to be 
canceled without regard to an abnormal 
termination exit. This facility of sharing 
an abnormal termination routine can be used 
even if the multitasking function (AP=YES) 
is not used. See AB parameter under FOPT 
Macro for more explanation. 

Reentrant Modules : Reentrant modules for 
CDMOD, DAMOD, ISMOD, MTMOD, PRMOD, SDMOD, 
and DIMOD allow a module to be shared by 



ATTACH Macro Considerations 



Only a main task can attach subtasks. A 
maximum of nine subtasks can be attached in 
the system at any given time. They can all 
reside in one partition or be spread among 
the three partitions in any combination. 
If a main task attempts to attach a tenth 
subtask to the system, a supervisor Event 
Control Block (SPVECB) is unposted 
(SPVECB+2, bit 0, set to zero), the address 
of the ECB is stored in general register 1 
of the main task, and bit of register 1 
is set to 1 giving the register a negative 
value. The main task can test register 1 
for a negative value and, if found, wait on 
register 1 until one of the nine subtasks 
is detached. Figure 1.11 illustrates the 
ECB. 

When a subtask is successfully attached, 
it has a higher priority than its main 
task. Therefore, control is passed to the 
subtask before it is returned to the main 
task. In addition, the registers of the 
subtask contain the same values as the 
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registers of the main task (both the 
general registers and floating point 
registers if specified) , with the following 
two exceptions: 

1. Register 1 of the subtask contains the 
address of the save area for the main 
task. 

2. Register of the main task contains 
the address of the byte immediately 
following the save area of the subtask 
(save area+96 if no floating point 
registers, or save area+128, if 
floating point registers) . 

The passing of the main task's registers 
to its attached subtask (s) is worth noting, 
because the subtask (s) can be under control 
of and use the main task's base register 
without initializing it. In addition: 

1. The subtask ID (a value from X'TO* to 
X'FO*) is stored in the subtask* s save 
area (save area+88, if no floating 
point registers or save area+120, if 
floating point registers) 

2. The address of the subtask 's entry 
point is stored in the save area (save 
area+13) ,and 

3. Byte 2 bits and 1 of the subtask 's 
ECB are set to (unposted). 

You should store the subtask name in the 
first eight bytes of the save area to be 
used for subtask identification when 
messages are printed on SYSLOG. 

In certain instances, a routine to be 
attached may not be in main storage. In 
this case, the entry point could be the 
label of a FETCH or LOAD routine that 
fetches the desired routine into storage. 

The following conditions cause 
cancelation of a main task (or possibly a 
subtask) . 

1. A main task has not issued the ATTACH 
macro (issued by another subtask). 

2. The subtask save area is not aligned 
on a doubleword boundary. 

3. The save area of the subtask being 
attached is not within the partition. 

4. The entry point of the subtask itself 
is not within the partition. 

5. The ABSAVE save area, if any, is not 
within the partition. 

6. The Event Control Block (ECB) of the 
subtask is not within the partition. 



If a main task is canceled, all subtasks 
in that partition are canceled. 



DETACH Macro Considerations 



A main task can detach any subtask (within 
its partition) , but a subtask can only 
detach itself. In addition, a subtask can 
be detached by issuing the CANCEL, EOJ and 
DUMP macros. If a subtask is detached, all 
pending I/O operations are completed before 
the DETACH operation is completed. In 
addition, any tracks being held by the 
subtask /are freed. 

If the subtask has an ECB, the ECB is 
posted (ECB+2, bit set to one) and any 
tasks waiting on the ECB are removed from 
wait state. The task with the highest 
priority then gains control. The 
supervisor ECB is also posted (SPVECB+2, 
bit set to one) and any main task waiting 
on it is removed from wait state. 

Although a main task can detach a 
subtask, it is generally more desirable for 
a subtask to detach itself. The entire 
system could be put into wait state if two 
(or all three) main tasks attempted to 
attach more than the nine subtasks allowed 
by the system. The following two examples 
show what could happen if the main task is 
allowed to detach its subtasks. 

Example 1 : All partitions attempt to 
attach five subtasks apiece. Each set of 
subtasks is independent and processing is 
such that each main task has a chance to 
attach a subtask before any one main task 
has attached all its subtasks. The entire 
system could then be placed in wait state, 
because the main task is not able to get to 
the routine to detach a subtask when it has 
successfully completed (it is waiting to 
attach another subtask) . 

Example 2 : Placing one or two of the three 
partitions in wait state is another 
situation that could occur, if all 
partitions attempted to attach five 
subtasks each. The Fl partition may attach 
all five of the subtasks. F2 partition may 
attach four of its five subtasks, and the 
BG partition may not attach any of its 
subtasks and, therefore, be in wait state. 
The main task of the F2 partition would 
also be in wait state because it still has 
one more subtask to attach. These subtasks 
remaining to be attached have to wait until 
one or more of the attached subtasks are 
detached. In addition, if the five 
subtasks in the F2 partition are dependent 
upon each other, the entire F2 partition 
could also be in wait state. Thus, only 
the tasks in the Fl partition may be 
executing. 
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The following conditions cause 
cancelation of a main task or a subtask: 

1. The main task detaches and does not 
pass the address of the subtask save 
area (if a subtask detaches and passes 
the save area address, it is ignored) . 

2. The main task detaches and the subtask 
is already canceling or canceled. 

3. The limits of the save area specified 
in the DETACH macro do not reside in 
the partition of the main task. If 
the main task is canceled, all 
subtasks within the partition are 
canceled. 

4. The subtask ID stored in the save area 
is not a valid subtask ID (hexadecimal 
70-FO) . 

In the last case, a check cannot be made 
if the value has been altered to that of 
another subtask ID. In this case, it would 
be possible for the wrong subtask to be 
detached because this is the only way the 
system can locate the task being detached. 
(This is also the reason why the main task 
must specify the save area of the subtask.) 
In addition, the system sets the invalid ID 
to binary zeros. 



Resource Protection 



2. 



a resource protected by an enqueue in 
one partition is not protected in 
another partition because an RCB is 
generated in its own partition and 
cannot be accessed by other 
partitions. Figures 1.11 and 1.12 
show the ECB and RCB. 



The second technique can only be 
applied to DTFDA, DTFIS, and DTFSD 
DASD files or those files you created 
using physical IOCS (EXCP/WAIT 
macros) . This is the track hold 
facility previously discussed. In 
contrast to the first technique, track 
hold applies across partitions. 



Reserved 
Byte 
* Byte 2 



Reserved 



Reserved 



Bit 0: Turned on (X'80 1 ) or normal 
termination of subtask . 

Bits Oand 1: Turned on (X'cC) if the 

subtask is abnormally terminated. 

Bits 2-7: Reseived 

Note: Other blocks that may be used as ECBs 
are CCBs, TECBs, and MICR CCBs since 
posting is done in bit of byte 2 of the 



The resource may be a file, an I/O device, 

a DTF, a work area or I/O area, or a set of ——-—«— 

non- reentrant code, etc. In general, it is | Figure 1.11. 

anything that has the possibility of being 

shared by two or more tasks. A means of 

protection has been provided so that two 

tasks sharing the same resource don f t 

access the resource at the same time. 

Resource protection can be accomplished 
in one of two ways, depending upon the 
resource to be protected. 



Event Control Block (ECB) 



The first technique applies to the 
types of resources just stated and 
requires three macro instructions 
(RCB, ENQ, DEQ) . The RCB macro 
generates a Resource Control Block 
(RCB) that is associated with the 
resource to be protected, but is not 
necessarily a part of that resource. 
When a resource is to be protected, an 
ENQ macro must be issued to enqueue an 
RCB. This places a hold on the RCB 
associated with the resource until the 
enqueuing task releases the RCB by 
issuing a DEQ macro to dequeue the 
RCB. These resource protection macros 
apply only within a partition and not 
across partition boundaries. That is. 



Byte 
Byte 0: 



Unused 



XXX 

1 2 3 



ECB address 
of Current 
Resource Owner 



XXX 

5 6 7 



Availability byte - All ones when resource is in 
- All zeros when not in used. 



Byte 4: Flag byte: 



Bit = 1, another task waiting for 
the resource. 
= 0, no other task waiting for 
the resource . 



Note: The address of the RCB is passed in register 1 



| Figure 1.12. Resource Control Block (RCB) 
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ENQ Macro Considerations 



The following conditions cause 
cancelation of a task: 



A resource can only be protected within a 
partition. 



Every subtask that enqueues a resource 
must have an ECB specified in its ATTACH 
macro (issued by the main task) and that 
ECB should not be used for any other 
purpose while a resource is enqueued. The 
address of the ECB is stored in the RCB. A 
main task does not require an ECB and has 
no means of specifying that it has an ECB 
(the address of which could be stored in 
the RCB) . When a main task enqueues a 
resource, the ECB address field of the RCB 
is set to binary zeros which identifies the 
resource owner as being the main task. 

A task requesting use of a resource is 
either enqueued and executed or put into 
wait state if the resource has already been 
enqueued by another task (byte of the RCB 
contains binary ones). In the latter case, 
the flag byte is turned on in the RCB (byte 
4, bit is set to one) and the ECB address 
of the current resource owner is stored in 
general register 1 of the task placed into 
wait state. 

The following conditions can cause 
cancelation of a task: 

1. A subtask does not have an ECB. 

2. A previous owner of a resource 
terminated without having dequeued the 
resource. (If the main task 
terminated, the entire partition was 
terminated. ) 

3. A task issued two consecutive ENQs for 
the same RCB without having issued an 
intervening DEQ. 

4. The limits of the RCB specified in the 
ENQ do not reside in the partition of 
the enqueuing task. 



DEQ Macro Considerations 



A resource can only be dequeued within a 
partition. Only the current owner of a 
resource can dequeue that resource. 

When an RCB is dequeued, byte is reset 
to binary zeros, and all tasks waiting for 
that resource are removed from wait state. 
The task with the highest priority obtains 
control. If no other tasks are waiting for 
the RCB, control returns to the dequeuing 
task. 



1. The RCB has the wait bit on in its 
flag byte (byte 4) and no waiting task 
which has been enqueued can be found 
for the RCB. This could be caused by 
the flag byte being inadvertently 
altered while a resource was enqueued. 

2. A subtask does not have an ECB. 

3. The limits of the RCB specified in the 
DEQ do not reside in the partition of 
the dequeuing task. 



Intertask Communication 



In certain situations, tasks may be 
dependent on other tasks within a 
partition. In these cases, macro 
instructions (POST, WAIT and WAITM) have 
been provided to permit synchronization of 
tasks for intertask communication. To use 
these macros, each task must have an Event 
Control Block (ECB) associated with it. 

When a particular task is performing a 
function and other tasks are waiting for 
its completion, it can indicate completion 
via the ECB by issuing a POST macro 
instruction. The tasks waiting for the 
completion may indicate this by issuing the 
WAIT macro instruction, designating the ECB 
on which the waiting is to be done. If a 
task is waiting for completion of a number 
of events (in which the order of completion 
is of no importance) , it can issue the 
multiple wait macro instruction (WAITM) 
designating a number of ECBs. 



POST Macro Considerations 



The tasks removed from wait state are those 
placed in wait state by ENQ, WAIT, or 
WAITM. When the SAVE parameter is omitted 
in the POST macro instruction, all tasks 
waiting on the specified ECB are removed 
from wait state. By specifying a SAVE 
parameter, only the task identified by the 
save area is removed from wait state. This 
parameter can be used for synchronizing the 
order in which tasks are to receive 
control. The synchronization technique 
prevents the priority task within a 
partition from gaining control. 

Be careful with this technique when the 
ECB to be posted is the ECB specified in 
the ATTACH macro and ENQ/DEQ macros are 
used, because DEQ also removes all waiting 
tasks from wait state. When the posting 
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task dequeues, all tasks waiting for the 
RCB are removed from wait state. 

A similar situation exists if the 
posting task dequeues before posting. The 
DEQ removes all tasks waiting for the RCB 
from wait state. Then, if it issues a POST 
to a particular task, the POST acts as a 
NOP because task selection gives control to 
the highest priority task ready to use the 
CPU. Although the task being posted is 
removed from wait state, the posting task 
is still active. If the posting task 
issues another POST to the same or another 
ECB, all other tasks waiting on the posted 
ECB are removed from wait state . To avoid 
this situation, use a second ECB when 
synchronizing tasks. It is your 
responsibility to reset the wait bit in the 
second ECB that is to be posted (MVI 
ECB+2,X , 00 f ) , so that tasks testing that 
ECB can be put in wait state. 

If a task associated with the specified 
save area cannot be found, the post 
operation is ignored and control passes to 
the highest priority task that is ready to 
run. 

A task can be canceled if the ECB 
specified in the POST macro instruction 
does not reside within the partition. 



Summary of Multitasking Considerations 



Maximum Number of Tasks : A maximum of 9 
subtasks can be attached to the system. 
They can all reside in one partition or be 
spread among the three partitions. Thus, a 
total of 12 tasks can be executed 
concurrently in the system. 

Subtask Priority : Each subtask must be 
initiated by a main task. A subtask has a 
higher priority than its main task. 
Subtask priority within a partition is 
determined by the order of attachment. The 
first subtask attachment has the highest 
priority in the partition, the next subtask 
has the second highest priority in the 
partition, etc. Of course, the priority of 
the partitions remains the same (i.e., Fl, 
F2, and BG) . If the highest priority 
subtask is terminated and later reattached, 
it will then be the lowest priority subtask 
within the partition, but still higher in 
priority than its main task, or any 
subsequent subtask that may be attached 
within that partition. 

Storage Protection : Because subtasks are 
subprograms within a partition, they have 
the same storage protect key as the main 
task. Therefore, the main task and its 
subtasks do not have storage protection 



from each other. The ENQ, DEQ, and RCB 
macros offer protection of resources, but 
only if all subtasks enqueue and dequeue 
before using the resource. They do not 
protect against inadvertent coding errors. 
In addition, the user must be careful when 
using ENQ/DEQ. If a higher priority 
subtask dequeues an RCB and does not enter 
wait state before enqueuing the RCB again, 
a lower priority task does not gain control 
of that RCB on which it has also enqueued. 
Thus, the lower priority task has to wait 
until the higher priority task terminates, 
before it can enqueue the RCB. 

Access To Communications Region : Only one 
communications region exists in a 
batched- job partition. Therefore, it is 
likely that only one task per partition has 
meaningful access to it. 

System Logical Units : Only one set of 
system logical units exist per partition 
(SYSLST, SYSRDR, etc). Therefore, 
interspersed usage by several independent 
tasks is not practical, although, if either 
the resource protection facilities or the 
intertask communication macros are 
employed, it can be done. 

Operator Intervention : While operator 
intervention is minimized for subtask 
initiation, SYSLOG will probably be used by 
all tasks within all partitions . The 
additional number of messages possible on 
one SYSLOG could possibly increase the 
responsibility of the operator and require 
more careful operation than in the past. 

STXIT Macro Usage : Subtasks may only 
provide their own AB and PC routines via 
the STXIT macro. IT and OC operations must 
be performed via the main task. An AB exit 
is not taken for a task when it is already 
in its AB routine (prevents looping on 
abnormal termination condition) . The task 
is canceled. 

Checkpoint Cons ider ation : Only main tasks 
can issue checkpoints. 

Track Hold Facility : Files being shared on 
DASD are not protected unless the HOLD 
option is specified by the various users 
(only applies to DTFDA, DTFIS, DTFSD, and 
DTFPH files). 

Register Usage : Although a subtask has the 
register values (2-15) of its main task 
upon being attached, the registers cannot 
be used for passing information between 
tasks once attached. (It is possible for a 
task to access the register save areas of 
other tasks within its partition.) 

Process Bound Tasks Considerations : 
Because subtasks are executed in priority 
order, a process-bound task can degrade 
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performance of lower priority tasks, or in 
extreme cases, even prevent execution of 
lower priority tasks until it has 
terminated. 

Task Synchronization ; Task synchronization 
is normally performed by POST, WAIT, and 
WAITM macros. This can also be done by 
ATTACH/DETACH or ENQ/DEQ providing you are 
careful, particularly when intermixing 
POST, ENQ/DEQ, and ATTACH/ DETACH macros. 
While POST may be used to free one waiting 
task, DEQ and DETACH can free all tasks 
waiting on the ECB posted, if the ECB is 
the same one specified in the ATTACH. 

Resource Protection ; The POST, WAIT, and 
WAITM macros are also used for resource 
protection, providing you are careful in 
your synchronization techniques. 

Resource Contention ; The problem of 
resource contention cannot be over 
emphasized in this system. It has already 
been pointed out that you can interlock two 
or more tasks, or even put the system into 
wait state when two or more partitions are 
concurrently attaching more than 9 subtasks 
or when two or more tasks (or partitions) 
are contending for the same sets of tracks 
while using track hold. In addition, a 
similar problem can exist when two or more 
tasks within a partition are enqueuing and 
dequeuing on the same set of RCBs. For 
example, if task A enqueues RCB 1 and task 
B enqueues RCB 2, task A is put in wait 
state when it attempts to enqueue RCB 2. 
The same is true when task B attempts to 
enqueue RCB 1. Neither task is able to get 
out of wait state to release the resource 
it has enqueued. 

This problem can be avoided by having 
each task, which shares common resources 
with other tasks, enqueue on the same 
resources in order. For example, task A 
enqueues on RCB 1 and then task B enqueues 
on RCB 1 (instead of RCB 2 first); task B 
goes into wait state. Task A can now 
enqueue on RCB 2 without entering wait 
state. When task A dequeues RCB 1, task B 
has the chance of enqueuing RCB 1 
(providing task A does not enqueue RCB 1 
again, before task B has a chance to 
reattempt its ENQ) . 

Another possibility of task interlock is 
for two tasks to wait on ECBs, with each 
task assuming that the other task will post 
the ECB on which it is waiting. 

Subtask Cancelation ; While the cancelation 
of a subtask frees tracks being held, and 
posts the subtask* s ECB (as. specified in 
the ATTACH macro) it does not dequeue any 
RCBs enqueued by that subtask. 
(Cancelation of a subtask executes the 
DETACH routines of the supervisor as well 



as the cancel routines.) Therefore, when 
the abnormal termination routine is 
entered, you should dequeue all RCBs that 
the subtask could have enqueued. 

If the subtask issues a DEQ for an RCB 
on which it has not enqueued, the DEQ is 
ignored and the supervisor returns to the 
subtask *s abnormal termination routine. 

Wait Considerations ; Although tasks can 
wait on ECBs to be posted by other tasks or 
on the ECBs of other tasks (in their own 
partition) , they cannot wait on the CCB of 
another task when that task has initiated 
the I/O operation. This does not mean that 
two tasks cannot share a CCB as a resource. 
It only means that the system identifies 
the CCB with the task doing the I/O 
operation. Therefore, only that task can 
be removed from wait state by the system. 
Any other task waiting on another task's 
CCB can only be removed from wait state by 
having the task that started the I/O 
operation issue a POST to the CCB. In this 
case, the CCB would function like an ECB. 
Also, note that the task doing the I/O 
operation must issue the POST macro after 
the WAIT macro rather than before the WAIT 
macro. Otherwise it would never enter the 
wait state or determine when the I/O 
operation is completed. 

Abnormal Termination ; In all abnormal 
termination conditions where an exit is 
taken to an abnormal termination routine, 
the register values are stored in the 
ABSAVE save area before the appropriate 
error code is stored in the low-order byte 
of register 0. To have this value 
available when looking at a storage dump, 
you should store (STC or ST) register in 
another save area upon entry into the 
abnormal termination routine. You will 
find that the SVC code shown in the "0S04I 
ILLEGAL SVC-..." message along with the 
error codes in register will be helpful 
in tracing program errors. See Debugging 
Aids section for additional information on 
abnormal termination codes. 



System Generation Guidelines 



The multitasking facility is provided at 
system generation time by specifying AP=YES 
in the SOPVR macro. When AP=YES is 
specified, MPS=YES and WAITM=YES are 
implied. To implement the other facilities 
related to multitasking, the following 
additional specifications are required at 
system generation time: 

• For abnormal termination support, 
AB=YES must be specified in the FOPT 
macro. AP=YES in the SDPVR macro is 
not required to utilize this function. 
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For multiple wait support, WAITM=YES 
must be specified in the FOPT macro. 
Although the multiple wait function can 
be used without specifying AP=YES, 
AP=YES cannot be used without 
specifying WAITM=YES. 



MULTITASKING EXAMPLES 



ATTACH Macro Example 



The normal procedure for attaching subtasks is as follows: 



MAINTASK 



BALR 
USING 



2,0 
*,2 



STXIT AB,MTABEND,MTSAVE 

3. MVC SUB1SAV(8),SUB1NAME Initialize subtask 1 save area 

4. ATST1 ATTACH SUBTASKl,SAVE=STlSAV,ECB=STlECB, ABSAVE=ST1ABSV 

5. LTR 1,1 Test if ATTACH is successful 

6. BNM ATST10K BR if successful 

7. WAIT (1) WAIT to retry ATTACH 

8. B ATST1 BR to retry 

9. ATST10K BCTR 0,0 Get end of subtask 1 save area 

10. ST 0,ST1SVEND Store ending address of subtask 1 save 

area 



11. 
12. 
13. 
14. 
15. 
16. 



SUBTASK1 



MT ABEND 



BALR 3,0 

USING * , 3 

ST l.MTSVAR 

STC 0,ABSVCODE 

C 1,=A(ST1ABSV) 

BE ST1ABEND 



Store address of main task save area 

Save ABTERM code 

Test if subtask 1 ABTERM 

BR if YES 



17. 



ST1ABEND 



EQU 



18. 




DS 


0D 


19. 


ST1SAV 


DC 


16D'0* 


20. 


ST1ABSV 


DC 


gD^o* 


21. 


ST1ECB 


DC 


F'0' 


22. 


MTSVAR 


DC 


F'0' 


23. 


ST1SVEND 


D d 


F «0' 


24. 


SUB1NAME 


DC 


C'SUBTASKl 


25. 


ABSVCODE 


DC 


X'O* 


26. 


MTSAVE 


DS 


9D 



Align on doubleword boundary 

Subtask 1 save area 

with floating point 

registers 

Subtask 1 AB save area 

Subtask 1 ECB 

Address of main task 

save area 

Ending address of 

subtask 1 save area 

Subtask 1 name 

Main task save area 
used by STXIT 
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Explanation for ATTACH Macro ; Statement 3 initializes the subtask save area with the 
name of the subtask which is used for messages for subtask identification when messages 
are written on SYSLOG. 

Statement 4 is the ATTACH of the subtask. SUBTASK1 is the entry point of the subtask, 
ST1SAV is the save area for the subtask, ST1ECB is its ECB, and ST1ABSV is the ABTERM 
save area for the subtask. In this case, the subtask is using the main task's abnormal 
termination routine. 

Statements 5 and 6 test for a successful ATTACH. If the ATTACH was not successful 
(nine subtasks already attached) , the main task waits until another subtask is detached 
and retries the ATTACH. If the ATTACH was successful, the main task stores the ending 
address of the subtask* s save area for later reference, if necessary. The main task can 
then continue to do other processing. 

Statement 11 is the entry point to the subtask. In this example, the subtask and the 
main task use different base registers. This may not be necessary, depending on program 
design. The subtask could have omitted the BALR and USING statements because 
addressability is available through the main task register (register 2) . The values in 
the main task registers are passed to the task. Therefore, register 2 would still be 
initialized. 

Statement 13 saves the address of the main task* s save area for reference by the 
subtask (if it is necessary for the subtask to name the main task in the POST macro 
instruction) . Statement 14 stores the ABTERM code when the abnormal termination routine 
is entered. This routine is shared by both the main task and subtask 1. Statements 15 
and 16 determine which task abnormally terminated (ABTERM save area of the task in error 
is stored in register 1) . Statement 18 aligns the save areas on a doubleword boundary. 

Statement 21 is the user-coded ECB for the subtask. 



( 
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DETACH Macro Example 



A subtask may detach itself or be detached by the main task. 

1. MAINTASK BALR 2,0 

2. USING *,2 



3 . ATST1 



ATTACH ST1 , SAVE=ST1SAV, ECB=ST1ECB 



4. ATST2 ATTACH ST2,SAVE=ST2SAV,ECB=ST2ECB 



5. 



6. ST1 



8. ST2 



DETACH SAVE=ST1SAV 



Detach subtask 1 



ST 



ST 



1,MTSVAR1 



STl+4 
1,MTSVAR2 



9. *DETACH Subtask 2 
10. DETACH 



Explanation for DETACH Macro ; The main task attaches two subtasks. When subtask 1 
completes processing, it indicates this to the main task. The main task then detaches 
subtask 1 by issuing a DETACH macro and specifying the save area for subtask 1 (statement 
5) . When subtask 2 completes its processing, it detaches itself (statement 10) . Note 
that an operand was not specified when subtask 2 detached itself, and that the comment 
was placed in a comments card (statement 9) . The comment would have acted as an operand, 
resulting in an error. 
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ENQ/DEQ and RCB Macros Examples 

EXAMPLE 1 ; When two subtasks share the same resource within a partition, they can use 
the resource protection macros as follows: 



1 . MAINTASK 
2. 



BALR 
USING 



2,0 
*,2 



SUBTASK1 



EQU 



4. 
5. 
6. 



SBTASK1A 



ENQ 


RCB1 


BAL 


4,WRITEDTA 


DEQ 


RCB1 



Protect resource. 
Write a record. 
Release resource. 



7. 



SBTASK1A 



8 . SUBTASK2 



EQU 



9. 


SBTASK2A 


ENQ 


RCB1 


10. 




BAL 


4,WRITEDTA 


11. 




DEQ 


RCB1 



Protect resource. 
Write a record. 
Release resource. 



12. 



SBTASK2A 



13. 



RCB1 



RCB 



Resource control block for WRITEDTA 



Explanation for Example 1 : Both subtask 1 and subtask 2 are sharing the same file using 
a common subroutine. The subroutine is not reentrant, and the file cannot use track 
hold. Therefore, it is necessary for each subtask to enqueue on the RCB associated with 
the resource and dequeue when the resource can be released for a waiting subtask. 
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EXAMPLE 2 ; In the following example, two subtasks are sharing a common processing 
routine defined in the first subtask. 

1. MTASK START 

2. ATTACH STASK1,SAVE=SAVE1,ECB=ECB1 

3. ATTACH STASK2,SAVE=SAVE2 r ECB=ECB2 

4. STASK1 ENQ RCBA Protect resource TOTAL. 

5. * Process TOTAL Used by STASK1 and STASK2. 

6. DEQ RCBA Release resource TOTAL. 

7. STASK2 EQU * 

8. B STASK1 Process TOTAL 

9. RCBA RCB RCB for resource TOTAL 
10. TOTAL DS Shared resource 



Explanation for Example 2 : The resource (TOTAL) in STASK1 is protected by the resource 
control block named RCBA. The protection remains in effect only if every segment of 
coding within the partition referring to TOTAL issues the ENQ macro before executing that 
selection of coding and subsequently dequeues that resource with the DEQ macro. This is 
effectively accomplished by branching to the same physical set of code. 

Note that the coding from statements 4-6 does not necessarily have to be reentrant, 
but you should ensure that values for constants associated with the subroutine do not 
have to be retained from one reference to the next, whenever the resource is used. If 
so, these values should be saved with the appropriate subtask and then later restored. 



> 
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EXAMPLE 3 ; In this example, the subtasks again share the same resource, but use 
different subroutines for processing that resource. 



1 . MTASK 



2. 



START 



ATTACH ST1,SAVE=SAVE1,ECB=ECB1 
ATTACH ST2,SAVE=SAVE2,ECB=ECB2 



4. STASK1 EQU * 

5 . ENQ RCBA 

6. * Update RESRCA 

7 . DEQ RCBA 

8. STASK2 EQU * 



Protect resource RESRCA 



Process using RESRCA 



Release resource RESRCA 



ENQ 



RCBA 



Protect resource RESRCA 



10. * Update RESRCA 



11. 




DEQ 

• 
• 


12. 


RCBA 


RCB 


13. 


RESRCA 


DS or DTF 



RCBA 



Process using RESRCA 



Release resource RESRCA 



RCB for resource RESRCA 
Shared resource 



Explanation for Example 3 : RESRCA can be simply an area in main storage or a file 
defined by a declarative macro. In either case, RESRCA is protected from subtask 2 while 
subtask 1 is operating on it. Thus, if all tasks enqueue and dequeue each reference to 
RESRCA, then RESRCA is protected during the time it takes to process instructions from 
that task's ENQ instruction to its DEQ instruction. This is readily apparent if RESRCA 
is in main storage. However, if it is a file, the record being operated upon is 
protected while in main storage, but it is not necessarily protected on the external 
storage device. 

If the file is on DASD, the HOLD function should be utilized, if possible. In any 
such situation, the priorities of subtasks must be considered for proper operation. 



< 
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POST Macro Example 



The POST macro can be used by one task to inform another task of the completion of some 
event, or it can release a number of tasks from wait state. 

1. MAINTASK BALR 2,0 

2 . USING * , 2 



3. 



4. 



ATTACH ST1 r SAVE=AREA1 , ECB=ECB1 
ATTACH ST2 , SAVE=AREA2 , ECB=ECB2 



ATTACH ST3 , SAVE=AREA3 f ECB=ECB3 



6. 
7. 



WAIT ECB1 
DETACH SAVE=AREA1 



Wait for completion of subtask 1 
Detach subtask 1 



8. 

9. ST1 



EOJ 
ST 



1,MTSVAR 



Store address of main task save area 



) 



10. 
11. 



12. ST1EOJ 

13. 

14. 



15. ST2 

16. ST2A 
17. 

18. 

19. ST3 

20. ST3A 
21. 

22. 



WAITM ECB 2, ECB 3 

NI 2(1) t X'7F' 



L 

POST 

WAIT 



EQU 

EQO 

POST 

B 

EQU 

EQU 

POST 



f MTSVAR 

ECB1,SAVE=<0) 

ECB1A 



ECB2 



ST2A 



ECB3 



ST3A 



23. 


MTSVAR 


DC 


F «0« 


24. 


ECB1A 


DC 


]?•()• 


25. 


ECB1 


DC 


F'O' 


26. 


ECB2 


DC 


F^O" 


27. 


ECB3 


DC 


F«0« 



Wait for subtask 2 or subtask 3 
Turn off WAIT bit 



Get address of main task save area 
POST ECB for main task 
WAIT to be detached 



POST ECB for subtask 1 



Save area address for main task 
Dummy ECB for subtask 1 
ECBs for subtasks 
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Explanation for POST Macro ; Subtask 1 (ST1) is dependent on input from subtask 2 (ST2) 
and subtask 3 (ST3). Therefore, it issues a WAITM on the ECBs for those subtask s. 
Notice that statement 11 resets the wait bit (set to 0) in the ECB that satisfies the 
wait condition. This ensures that the wait bit is off before reissuing the WAITM. 
(subtask 1 is the highest priority task and, therefore , would gain control before subtask 
2 and subtask 3. The result is that the WAITM is always satisfied from the first 
operation. ) Initially, subtask 1 is placed in wait state by the WAITM. Control is then 
passed to subtask 2 and then to subtask 3. When either of the two subtasks has the 
necessary data for subtask 1, it posts its ECB that removes subtask 1 from wait state. 
When subtask 1 finishes its processing, it posts its ECB causing the main task to be 
taken out of wait state which then detaches subtask 1. 



WAITM Macro Example 

A task issuing the WAITM macro should ensure that if an event has the possibility of not 
occurring (perhaps the task posting the event was terminated) , the waiting task should 
allow an eventual outlet. This outlet, as shown in the following example, can also wait 
on the terminating ECB of the task that was to perform the preferred event. 



1 . MAINTASK 
2. 



BALR 
USING 



2,0 
*,2 



3. 



ATTACH ST1 , SAVE=SAVE1 , ECB=ECB1 



4. 
5. 
6. 



11. 
12. 
13. 
14. 
15. 



WAITM ECB2,ECB1 

NI 2(1),X , 7F* 

B 4(1) 



7. PREVENT EQU 



8. TEVENT 



10. ST1 



ECB1 
ECB2 



EQU 



EOJ 



EQU 



POST 

DC 

B 

DC 

B 



ECB2 

F «0« 

TEVENT 

F'O* 

PREVENT 



Wait for preferred or secondary event 

Turn off WAIT bit 

BR to branch in vector table 



Main task preferred event 



Main task secondary event 



Main task end of job 



POST completion of preferred event. 
ECB for secondary event 
Vector BR to secondary event 
ECB for preferred event 
Vector BR to preferred event 



Explanation for WAITM Macro ; In this example, the WAITM macro contains a preferred event 
as the first operand and a secondary event as the second operand. The preferred event is 
the posting of ECB2 after subtask 1 completes its calculation. If subtask 1 terminated 
before its calculation is completed, the supervisor posts the ATTACH macro ECB of subtask 
1, ECB1, and the secondary event can satisfy the WAITM macro. In either event, after the 
WAITM macro is satisfied, the address of the posted ECB is contained in register 1. This 
address can select a problem program routine. 



In this particular case, a branch instruction points to a table containing a list of 
ECBs with corresponding branch instructions to the routine to be given control when the 
ECB is posted. This table can easily be expanded to include up to a maximum of 16 ECBs 
(due to the WAITM format used). 
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STXIT AB Macro Example 

The STXIT AB macro instruction establishes linkage to an abnormal termination routine for 
either a main task or a subtask. 



1. 


MAINTASK 


BALR 


2,0 


2. 




USING 


*.2 


3. 




STXIT 


AB, MTABEND, MTABSV 



4. 



Initialize AB exit 



ATTACH ST1 , SAVE=SAVE1 , ECB=ECB1 , ABSAVE=STlABSV 



6. 



7 . MTABEND 

8. 

9. 



10. 

11. ST1ABEND 



12. 



13. ST1 



14. ST2 



ATTACH ST2 , SAVE=SAVE2 , ECB=ECB2 



ATTACH ST3,SAVE=SAVE3,ECB=ECB3 



STC 

C 

BE 



CANCEL 
EQU 



0,MTABCODE 

1,A(ST1ABSV) 

ST1ABEND 



CANCEL ALL 



EQU 



STXIT AB,ST2ABEND,ST2ABSV Initialize subtask 2 AB exit 



15 . ST2ABEND STC 



16. 



17. ST3 



18. ST3ABEND STC 



19. 



Save AB code 
Test if ST1ABTERM 
BR if YES 



CANCEL for main task cancels all tasks 



CANCEL ALL for subtask 1 



CANCEL 



STXIT 



CANCEL 



0,ST2ABCOD 



Save AB code 



CANCEL for subtask 2 



AB,ST3ABEND,ST2ABSV Initialize subtask 3 AB exit 



0,ST3ABCOD 



Save AB code 



20. 




DC 


0D 


21. 


MTABSV 


DS 


9D , 0« 


22. 


ST1ABSV 


DC 


gD'O* 


23. 


ST2ABSV 


DS 


9D , 0" 


24. 


ST3ABSV 


DS 


9D'0* 


25. 


MTABCODE 


DC 


X'0 f 


26. 


ST2ABCOD 


DC 


X'O' 


27. 


ST3ABCOD 


DC 


X'O' 



Align on doubleword boundary 
Main task AB save area 
Subtask 1 AB save area 
Subtask 2 AB save area 
Subtask 3 AB save area 
Save area for AB codes 
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Explanation for STXIT Macro ; Statement 3 establishes linkage to the abnormal termination 
routine for the main task. Statement 4 attaches subtask 1 and indicates to the 
supervisor that it will use the main task's abnormal termination routine by specifying 
the ABSAVE parameter. Note that the main task*s abnormal termination routine tests for a 
main task or subtask 1 abnormal termination by comparing the address in register 1 to the 
address of subtask l's AB save area. 

When the main task or subtask 1 cancels (CANCEL ALL), the entire partition is 
canceled. Subtasks 2 and 3 initialize their own abnormal termination exits because they 
use their own abnormal termination routines. When either subtask 2 or subtask 3 cancels, 
only that subtask is terminated; the other tasks within the partition continue 
processing. 



i 
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Track Hold and Reentrant Modules Example 

Although track hold applies across partitions, this example only shows two subtasks 
sharing the same DA file and the same DA modules. It is possible that a similar set of 
routines could be executing in a second partition also sharing the file with the first 
partition, but that partition would have its own DA module - 

1. MAINTASK START 

2. ATTACH ST1,SAVE=AREA1,ECB=ECB1 



3. 



ATTACH ST2,SAVE=AREA2,ECB=ECB2 



4. ST1 



OPEN 



DAFILE1 



OPEN DA master file 



5. 
6. 



LA 
READ 



13 r DASAVEl 
DAFILE1,KEY 



Initialize register 13 with DA save area 
Read and hold record 



7. 



WAITF 



DAFILE1 



8. 

9. 

10. 



WRITE 
WAITF 
FREE 



DAFILE1 , KEY 

DAFILE1 

DAFILE1 



Write updated record 
Release track 



11. DAFILE1 



DTFDA HOLD=YES , RDONLY=YES , 



12. ST2 



OPEN 



DAFILE2 



OPEN DA master file. 



13. 




LA 


13,DASAVE2 


14. 




READ 


DAFILE2,KEY 


15. 




WAITF 

• 


DAFILE2 


16. 




• 
WRITE 


DAFILE2,KEY 


17. 




WAITF 

• 


DAFILE2 


18. 




• 
FREE 

• 


DAFILE2 


19. 


DAFILE2 


• 
DTFDA 

• 


HOLD=YES , RDONLY: 


20. 




• 
DAMOD 

• 


HOLD=YES f RDONLY: 


21. 


DASAVEl 


• 
DS 


8D , f 


22. 


DASAVE2 


DS 


SD^' 



Initialize register 13 with DA save area 
Read and hold record 
From DA master file 



Write updated record 



Release track 



Save areas used by DAMOD 
when shared and reentrant 
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Explanation for TRACK HOLD and REENTRANT Modules ; Because both subtasks share the same 
file, HOLD=YES and RDONLY=YES must be specified in both DTFs and in the DAMOD. In 
addition, before any I/O operation is issued (READ, WRITE, or WAITF) , register 13 must 
contain the address of a unique save area to store the registers used by the module. 
Register 13 is not altered between I/O operations executed by a given sub task, and 
therefore, only needs to be initialized once. If other reentrant access methods were 
used by the subtask, register 13 would have to be initialized for each LIOCS function. 



FOPT Macro 



OPERATOR COMMUNICATIONS SUPPORT (OC) 



foreground partitions, the operator presses 
the REQUEST key on the 1052 console and, in 
reply to the ATTN routine statement 'READY 
FOR COMMUNICATIONS* , types "MSG Fl* or *MSG 
F2». 



Operator Communications (OC) refers to the 
processing of an external interrupt by a 
problem program. In a multitasking 
environment, only the main task can 
communicate via the OC linkage. By 
specifying OC=YES, a table (OC option 
table) is generated within the supervisor 
(see Figure 1.13). When the problem 
program issues the STXIT macro, the address 
of its external interrupt routine is moved 
to the OC option table. The user's routine 
is terminated by issuing the EXIT macro. 
When OC=YES is specified, support is 
available to all partitions. Figure 1.20 
illustrates a sample program using this 
support . 

The Tape Compare Utility program 
requires this support. OC=YES is also 
required if emulator program operator 
services are to be requested through the 
INTERRUPT key. 



Operational Considerations 



To cause an external interrupt for the 
background partition, the operator presses 
the INTERRUPT key on the CPU console. To 
cause an external interrupt for the 



INTERVAL TIMER SUPPORT (IT) 



This parameter generates programming 
support for the hardware timer feature. 
The timer consists of two parts. The first 
part keeps track of the time-of-day and is 
used to time-stamp system time. The second 
part of the timer allows a problem program 
to set a time interval (via SETIME macro) . 
By using the STXIT, EXIT, and TECB macros, 
a specific routine within the problem 
program is entered when this time interval 
elapses. In a multitasking environment, 
only the main task can set a Timer Event 
Control Block (TECB) . 

The interval timer is in addition to and 
separate from the time-of-day support 
generated by the specification of the 
TIMER= parameter of the CONFG macro. When 
interval timer support is specified (i.e., 
IT=BG, Fl, or F2) , TIMER=YES is assumed for 
the CONFG macro. Support is only available 
to one partition at a time as defined at 
system generation time. The TIMER command 
can change the assignment from one 
partition to another after the supervisor 
has been generated. QTAM requires IT=F1. 
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PC Option Table and OC Option Table: 



word ■ 



word ■ 







H 



No STXIT given: a =0 

STXIT issued: a = address of the user program check (operator communications) routine 

STXIT issued when the user routine is already in use: a = complement of user program check (operator communications) 

routine address 



No STXIT given: b = 

STXIT issued: address of the user save area 



IT Option Table 



c d 



word 



word 



El 



No TECB or STXIT issued: c = 

TECB issued: c = address of the timer event control block 

STXIT issued: c = address of the user interval timer routine 

STXIT issued when user routine is already in use: c = complement of the user interval time routine address 







No TECB or STXIT issued: d = 

TECB issued: d = complement of the TECB address 

STXIT issued: d = address of the user save area 



AB Option Table 



H 



word 



word 



No STXIT given: e =0 

STXIT issued and rtnaddr parameter passed: e=address of entry point of user's abnormal termination routine. If AP 

(asynchronous processing) is supported, the main task and subtasks may have the same or different AB routines. 
When a subtask is attached after a STXIT AB macro has been issued by the main task, the subtask will receive 
the AB routine address specified by the main task only if the ATTACH macro for that subtask has the ABSAVE 
parameter specified. The subtask can override this by issuing its own STXIT AB macro. 



□ 



No STXIT given or no save area parameter passed: f = 

STXIT issued and save area parameter passed: f = address of a 72- byte save area used by the supervisot to store the 
old PSW and general registers 0-15. 



Each table address (less 8 bytes) is found in the communications region at the byte locations specified below. The labels 
shown identify the first byte of the corresponding table. 



Table 

PC 
IT 

OC 
AB 



Bytes in COMREG 

100-101 (XW-'oS 1 ) 
102-103(X'66 , - , 67') 
104-105(X'68'- , 69') 
^-^(X'OC'-'OD') 
of extension 



Label 

PCTAB 
ITTAB 
OCTAB 
ABTAB 



Figure 1.13. Option Tables 
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PROGRAM CHECK SUPPORT (PC) 



Program Check (PC) support generates a PC 
table within the supervisor (see Figure 
1.13). The PC table contains the address 
of a user program check routine. This 
address is placed in the table via the 
STXIT macro issued by the problem program. 
If the STXIT PC linkage is established and 
a program check within this program occurs, 
the supervisor gives control to the user's 
routine instead of canceling the job being 
run in this partition. The support is 
extremely advantageous when using LIOCS 
(e.g., files can be closed before job 
termination) . If a program check occurs in 
a routine being executed from the logical 
transient area (LTA) , only the task 
associated with that routine is abnormally 
terminated. 



TEB : The system generates the number of 
tape unit error blocks specified by n. TEB 
support automatically collects and writes 
magnetic tape unit status on SYSLOG at the 
end of every job utilizing these units. 
The n must be at least equal to the number 
of tape units and/or tape cartridge readers 
attached to the system. (TEB is the only 
one of the three options supporting the 
tape cartridge reader.) Additional TEBs 
should be specified for possible future 
expansion. 

ESTV ; The system generates a TEBV table 
with a status block and the number of error 
blocks specified by the n in 
TEBV=(DASD,n) j (SYSLOG, n). ESTV transients 
format and write the error records on DASD 
or SYSLOG each time a particular volume is 
ended by CLOSE, EOV,- EOJ, or abnormal 
termination . 



In a multitasking environment each 
subtask and main task may have its own PC 
routine. A PC routine can be shared by 
more than one task within a partition. 
This can be done by issuing a STXIT macro 
in each task with the same routine address 
but with separate save areas. To 
successfully share the same PC routine it 
must be reentrant (capable of being used 
concurrently by two or more tasks) . 

Figure 1.20 shows a sample program using 
this support. Refer to Supervisor and I/O 
Macros listed in the Preface for further 
information on problem program macro 
formats and their use. 



TAPE ERROR RECORDING 



The three options and their system 
generation specifications for tape error 
recording are: 

• Tape Error Block (TEB) by unit, 
TEB=n. 



For TEBV=(DASD,n), the ESTV recorder 
file (ESTVFLE) must be formatted and opened 
for the collection of statistics using 
ESTVFMT, the ESTV format program. SYSREC 
is the system logical unit used to collect 
ESTV statistics. The information written 
on ESTVFLE may be retrieved by executing 
the ESTV dump program, ESTVUT. 

For TEBV= (SYSLOG, n), ESTV transients 
format and write the data on SYSLOG and do 
not access any intermediate storage device. 

EVA ; The system generates a TEBV table and 
prints a message on SYSLOG when the 
temporary read error threshold (r) or 
temporary write error threshold (w) has 
been exceeded on a currently accessed tape 
volume. The number of SIOs is also 
included in the message. EVA can be used 
for both labeled and unlabeled tape 
volumes. Only the first four bytes of the 
status block portion of the TEBV table are 
generated if TEBV is not specified also. 
The status block is followed by the number 
of error blocks specified by the n 
parameter. 



• Error Statistics by Tape Volume (ESTV) , 

TEBV=(DASD,n) or TEBV=(SYSLOG,n) . 

• Error Volume Analysis (EVA) , 

EVA=(r,w,n). 

Any one or any combination of these options 
may be selected. If more than one is 
included, the n must be the same for each. 
A TEB table is generated for the TEB 
option. A TEBV table is generated for the 
ESTV and EVA options. Status information 
contained in these tables is shown in 
Figure 1.15 and 1.16. Figure 1.14 shows 
the I/O interrelationship. 



System Generation Guidelines 



The FOPT macro checks the options in the 
following order: TEB, TEBV, EVA. An 
invalid specification for any option (n is 
outside the range 0-254) results in NO 
being assumed for that option. If TEB has 
been validly specified, the TEBV n will 
take on the value of the TEB n. If either 
TEB or TEBV has been validly specified, the 
EVA n will take on the value of the 
previously set n. If any n does not have 
the same value as an earlier valid n, an 
MNOTE is issued. 
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KEY: 

NICL (Number in Class) 

FICL (First in Class) 

LUB (Logical Unit Block) Table 
PUB (Physical Unit Block) Table 

FOCL (First on Channel List) 

TEB (Tape Error Block by Unit) 
TEBV (Tape Error Block by Volume) 

FAVP (First Available Pointer) 
JIB (Job Information Block) 

CHANQ (Channel Queue) Table 

LUBID (LUB Identification) 
REQID (Requestor Identification) 
LUBDSP (LUB Displacement) 
FLPTR (Free List Pointer) 
SAB (Seek Address Block) 

TKHDTAB (Track Hold Table) 

THFLPTR (Track Hold Free List Pointer) 
TKREQID (Track Requestor Identification) 
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: The first byte contains the number of system class units. The second, third, and fourth bytes contain the number of 
programmer class units (BG, F2, Fl) (Figure 1 .21). 

: The first byte points to the first system class unit in the LUB table. (Always the first LUB table entry.) The second byte 
points to the first programmer class unit in the LUB table BG area. The third points to the first programmer class unit in 
the LUB table F2 area. The fourth points to the first programmer class unit in the LUB table Fl area (Figure 1 .21). 

: The first byte points to a PUB table entry (if the logical unit is assigned) or contains X'FF'. The second byte points to a 
JIB table entry or contains X'FF 1 (Figure 1 .21). 

: The first two bytes contain the channel and unit address of the physical device; the third a CHANQ pointer; the fourth 
a TEB pointer; the fifth device type codes; the sixth a device characteristic code or a SAB pointer; the seventh the 
channel scheduler flag; and the eighth has the job control flag (Figure 1 .30). 

: The first byte points to the first PUB (highest priority) on channel zero. The next byte points to the first PUB (highest 
priority) on channel one, etc. A hexadecimal FF indicates the associated channel is not supported. 

: One TEB is built for each tape unit at supervisor generation time if tape error statistics by unit are required (Figure 1.15). 

: One TEBV is built for each tape unit at supervisor generation time if tape error statistics by volume or error volume 
analysis are required (Figure 1 .16). 

: A one -byte pointer to the next available JIB entry. 

: The first two bytes contain extent or LUB information. The third contains ownership and JIB flags. The fourth contains 
JIB chaining information (Figure 1 .22). 

: The first byte contains the chain field (a pointer to the next in queue). The last three bytes contain the CCB address 
(Figure 1.29). 

: A one -byte pointer to the LUB making the I/O request. 

: A one -byte pointer to the program containing the CCB (Figure 1 .29). 

: A one -byte value equal to the absolute LUB number (CCB byte 7). 

: A one -byte pointer to the next free entry in the channel queue (Figure 1 .29). 

: A four -byte (BCCH) address that is the current disk address of the device plus a fifth byte that contains a Track Hold 
Table pointer or X'FF' . If the Track Hold function is not supported, the fifth byte contains X'00' . 

: The first byte contains a pointer to the next available entry (or X'FF'); bytes 2-4 have CCB address of the requesting 
task; bytes 5-10 have disk address (BBCCHH) of track being held; byte 1 1 has key of owning track; and byte 1 2 has 
two uses: bit = 1 means a task is waiting for the track, and bits 4-7 count the number of holds on the track. Note 
that the number of holds is one greater than the value wf bits 4- 7 of the last byte . 

: A one -byte pointer to the next free entry in the Track Hold Table. 

: A one -byte pointer to the PIB of the task requesting I/O . 



Figure l.in. I/O Table Interrelationship 
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TEBTAB 



TEB Table 



TEB 1 



TEB 2 



TEB 4 



TEB 5 



TEB 6 



Byte 

- Error recover/ retry count. 

1 - Permanent read data check error count. 

2 - Number of times the read data check error routine is entered. 

3 - Number of times the write data check error routine is entered. 

4 - Write skip (erase gap) count. 

5 - Noise record count. 

One TEB is generated for each 2400 series or 3420 magnetic tape or 2495 Tape Cartridge Reader unit if the FOPT macro con- 
tains the TEB = n parameter. Job control resets each TEB at normal or abnormal End-of-Job. An unused TEB contains 
HEX'FFOOOOOOOOOO'. A TEB is referenced from byte 3 of a magnetic tape unit PUB. 

Bytes 70 and 71 (X'46 l - , 47' ) of the communications region contain the address of the TEB table entry. Label TEBTAB 
identifies the first byte of the table. 



Figure 1.15. Tape Error Block 



i 



60 DOS System Programmer's Guide 



Decimal 




Byte 




Displacement 


Label 


Length 


Description 




TEBVTAB 




Symbolic address of the TEBV Table 


(TEBV Stc 


tus Block port 


on of TEI 


N Table - Note 1) 





TEBLEN 




Length of TEBV Error Block (for each Error Block generated) 


1 


TSBLEN 




Length of TEBV Status Block (4, 6, or 22 bytes - see Note 1) 


2 


EVARTH 




EVA Read Error Threshold 


3 


EVAWTH 




EVA Write Error Threshold 


4 


TEBSTAT 




DASD ESTV File Status 


5 


TEBUDC 




ESTV Label Update Counter 


6 


TEBDEV 




Data Set Device Code 


7 


UPXTNT 


4 


Disk Address of Upper Extent of Data Set (cchh) 


11 


TEBRPT 


1 


Number of Records per Track 


12 


NXTESR 


5 


Disk Address of Next Available Space for Data Record (cchhr) 


17 -1 


ESTVLABL 


5 


Pointer to ESTVFLE Label in VTOC (cchhr) 


(TEBV Err 


or Block Portic 


>nof TEBN 


/ Table - Note 2) 


22 


TEBV 




Status Indicator (giving status of posting and writing error conditions) 


23 






Usage Indicator (X'00'=TEBV Error Block in use; X'FF'=Error Block generated but not serving any tape unit) 


24 






Retry Counter 


25 






Permanent Read Errors 


26 






Temporary Read Errors 


27 






Temporary Write Errors 


28 






Erase Gaps 


29 






Noise Blocks 


30 






Permanent Write Errors 


31 






Clearer Actions 


32 




2 


Number of Start l/Os 


34 




6 


Volume Serial Number (Volume ID) 


40 (Be 


gin repeating 


bytes 22 - 


39 for second TEBV Error Block) 

• 


Note 1: The TEBV Table is composed of one Status Block and (n) Error Blocks and is addressed symbolically by TEBVTAB. The table is 


generated if EVA and/or ESTV are included in the system. 


The size of the TEBV Status Block is determined by supervisor options in the FOPT macro at generation time: 


• When EVA is chosen without ESTV, the TEBV Status Block is four bytes long (bytes 0-3), followed by TEBV Error Blocks, 


so that bytes 4-21 are omitted. 


• When ESTV output is on SYSLOG, the TEBV Status Block is six bytes long (bytes 0-5), followed by TEBV Error Blocks, 


so that bytes 6-21 are omitted. 


• When ESTV output is on DASD, the TEBV Status Block is 22 bytes long (bytes 0-21), followed by TEBV Error Blocks. 


Note 2: The number of TEBV Error Blocks generated corresponds to the (n) parameter in the FOPTmacro for TEB, TEBV, or EVA options. 


A TEBV Error Block always contains 18 bytes, as shown in bytes 22-39 of this figure. The TEBV Table, therefore, is composed 


of one TEBV Status Block (with the length dependent upon supervisor generation options as described in Note 1), followed by 


(n) number of 18 -byte TEBV Error Blocks. 



Figure 1.16. TEBV Table Showing Status Block and Error Blocks 
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SEEK SEPARATE SUPPORT (SKSEP) 



When DASD devices are command chained, they 
monopolize the channel until channel end 
for the device associated with the last CCW 
in the chain is reached. This means that 
the channel is unavailable for use by other 
partitions requiring I/O operation of other 
DASD devices on the channel. 

The seek separation feature was designed 
to improve the performance of systems 
running under DOS. This feature enables 
the supervisor to separate a seek from its 
associated read or write so that the seek 
can be separately scheduled. This means 
that multiple seeks can be issued to 
devices on a channel, and the reads and 
writes scheduled as the seeks are 
completed. As this is a supervisor 
function, it automatically applies to 
programs written at any language level 
and/or operated in any of the three 
partitions. As the number of devices on a 
channel increases, the benefits derived 
from this feature increase. The 
implementation of this feature is such that 
when a seek has been issued to a device, 
the arm cannot again be shifted until the 
I/O operation that initiated the seek has 
been completed. In other words, arm 
stealing has been prevented. After seek is 
issued, the channel is available for 
scheduling any other I/O operations. In a 
multiprogramming environment, this feature 
is particularly important when the 
different partitions have a mix of 
input/output requests for a single channel 
with multiple direct access devices. 

The seek separation capability is 
provided by unchaining the user's seek and 
by posting the seek separation bit (X'10* 
of the 13th byte of the user's CCB) and the 
"Wait for Device End" bit in the user's 
CCB. When START I/O is performed on the 
new unchained seek, channel end is 
immediately sent back from the control 
unit, thereby freeing the channel for 
performing seeks to other units on the 
channel. When the device end interrupt 
occurs at the completion of a seek, the 
seek separation and "Wait for Device End" 
bits are turned off, the seek is rechained 
to the remaining CCWs for the I/O request, 
and the device is not dequeued. A START 
I/O is now performed on this unit that has 
its arm already positioned at the correct 
cylinder. 

Specifying this feature generates a Seek 
Address Block (SAB) within the supervisor 
(refer to Figure 1.14). Each DASD device 
has an entry in the SAB containing the 
current disk address for that device. Each 
time the user performs a seek, his seek 
address is compared with the entry for that 



device in the SAB. If they are equal, no 
seek separation is performed. If they are 
not equal, the seek address replaces the 
current entry in the SAB, and seek 
separation is performed. Each user's DASD 
CCW chain must start with a long seek 
(X'07') in order to use this feature. 



System Generation Guidelines 



Specifying SKSEP=YES indicates support for 
all DASD devices specified by the DVCGEN 
macro at system generation time. N is the 
number of DASD devices to be supported and 
cannot be less than the number of DASD 
devices specified at system generation. 



PHYSICAL TRANSIENT OVERLAP SUPPORT (PTO) 



Physical Transient Overlap (PTO) support 
allows the system to: 

• Overlap I/O operations in the error 
recovery routines (ERP) with problem 
program processing. 

• Overlap I/O time required to fetch user 
programs and system transient routines 
into main storage with problem program 
processing. 

The PTO option allows other tasks to be 
selected when an I/O operation is being 
performed during one of the following: 

• Fetching a phase (SVC 1) 

• Fetching a logical ($$B) transient (SVC 
2) 

• Fetching a physical ($$A) transient 
(SVC 3) 

• Loading a phase (SVC 4) 

• Loading a phase header (SVC 23) 

• Modifying the system communications 
region via MVCOM macro (SVC 5) 

• Fetching of the ATTN routine 

• Performing ERP I/O operations 

For example, if an error occurs in the 
background partition while reading a tape 
record, an error recovery routine is called 
into the physical transient area to reread 
the record up to 100 times. Each reread 
operation requires time to read the record 
itself plus time to backspace the record 
before reading it again. Without PTO, the 
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) 



entire 100 rereads by the error recovery 
routine would not be overlapped with other 
processing and other tasks would not 
receive control during this interval- With 
PTO f I/O time is overlapped and available 
to the foreground partitions for processing 
until another error recovery routine or 
system transient routine is required. 

Another advantage of PTO involves fetch 
I/O time. Fetching requires one or more 
searches of the library directory on 
SYSRES, reading of the directory into the 
physical transient area, and searching for 
and reading one or more records of the 
program or transient into the proper area 
of main storage. This involves several 
disk I/O operations. PTO allows the fetch 
I/O time to be overlapped with processing 
by any partition requiring CPU time (in 
priority sequence) until another fetch or 
other use of the physical transient area is 
required . 



Data chaining and command chaining are 
not used. 



3. The CCB associated with the operations 
does not request any sense information 
(CCB+12 set to X'20") and/or does not 
have either "accept unrecoverable I/O 
error", "post at device end", or "user 
error routine" bits on (CCB+2 set to 
X'lS* or any combination of these). 
In other words, no error checking is 
required. 



4. The CCW must have either an X'01' or 
X'O^ command code (i.e., only a WRITE 
operation) . 

5. For user messages, the CCW and the 
message must reside within the 
partition issuing the write operation. 

If these conditions are not met, the 
console operation is handled in a normal 
manner . 



CONSOLE BUFFERING SUPPORT (CBF) 



Previously, a system component could hold 
up the system and degrade throughput 
performance whenever an I/O operation was 
issued to the console typewriter (1052), 
followed by a WAIT. The console buffering 
option (CBF) alleviates this situation by 
queuing write operations to a 1052, 3210, 
or 3215 and returning control immediately 
to the routine that issued the write with 
the WAIT bit posted. The user's WAIT is 
satisfied immediately, rather than at 
actual I/O completion. Each message is 
assigned a buffer containing the message 
itself and control blocks for I/O interrupt 
handling (Figure 1.17). The system writes 
the message from the buffer on the 1052, 
3210, or 3215 as soon as possible while 
user- processing continues. 

The CBF facility is used only for write 
operations which require no user error 
handling. Only those messages that meet 
the following criteria are buffered: 

1. Messages cannot exceed 80 characters. 



You have the option of specifying the 
number of buffers required for queuing 
messages, but the total may not exceed 50. 
If a buffer is not available, your WAIT is 
not satisfied until a buffer is freed. At 
least one buffer should be specified for 
each partition or task issuing messages so 
that buffers are available and the task can 
continue processing while the message is 
being printed. Job control often issues 
several console messages in succession; 
therefore several additional buffers should 
be specified for partitions that use job 
control frequently. 

Another factor to be considered in the 
selection of the CBF option is extra 
channel usage. Specification of the CBF 
option and selection of the CHANQ default 
(6 channel queue entries), results in the 
number of buffers specified being added to 
the CHANQ default. However, when both the 
CBF and CHANQ options are specified, it is 
recommended that the number of CHANQ 
entries desired be increased by the number 
of buffers specified. Otherwise, the 
number of entries generated in the channel 
queue will be less than desired. 



Section 1: Supervisor Planning Concepts 63 



CBTAB 



XX 



CBINUSE 



CBNEXT 



Points to next 
available buffer 



7 
CBCCW 


8 20 
CBCCB 


21 23 
CBPREX 


24 103 
CBDATA 



































CBTABND 



The Buffer Table is a 104 multiplied- by- n byte area of main storage, where n is 1 -50. Each buffer entry in the table is 104 bytes. 
CBNEXT is a halfword constant that points to the next available buffer entry. It is initialized with the address of CBTAB and is 
incremented by 104 every time a buffer is used, so that it points to the next entry. When its value becomes greater than CBTABND, 
it is reinitialized with the value CBTAB. 

CBINUSE is a one- byte counter that contains the number of entries currently in use. It is incremented whenever a buffer is used and 
is decremented at dequeue time when the buffer becomes free. 

Each buffer entry contains the following fields: 

Displacement: CCW moved from requestor core. The data address portion of the CCW is modified to 
point to the data portion of the buffer. 

8 CCB moved from requestor core. The CCW address in the CCB is modified to point to 
the CCW in the buffer. 

21 Prefix. SYSLOG ID moved from problem program PIB. The prefix is printed with the 
data to identify BG, Fl, or F2 partitions. 

24 Data moved from requestor core. 
Figure 1.17. Console Buffering Table and Work Areas 



| INDEPENDENT DIRECTORY READ- IN AREA (IDRA) 



An independent directory read-in area 
(IDRA) can be included if the option is 
specified at system generation time . The 
funcion of this area is to enhance 
performance by reducing contention for the 
physical transient area (PTA) on fetches 
from the core image library. During the 
time the physical transient area is busy, 
fetches from other partitions can be 
processed. 



System Generation Considerations 



idra=/no ) 

I YESi 

The YES option causes generation of the 
IDRA area in the supervisor. IDRA requires 
MPS=YES or BJF, and PTO=YES. 

If IDRA=NO, the core image library 
directories are loaded and scanned in the 



PTA. If IDRA=YES f the core image library 
directories are loaded and scanned in the 
IDRA. The IDRA is used for all supervisor 
calls that require reading of directories. 



COMMAND CHAINING SUPPORT (CCHAIN) 



Command chaining support (CCHAIN=YES) 
allows the DOS error routines to retry an 
I/O operation starting with the last CCW 
executed rather than at the beginning of 
the chain. Under normal error recovery 
procedures, the entire CCW chain is 
reexecuted. To utilize the CCHAIN support, 
you must indicate in the CCB macro 
instruction that you want the error 
procedures to retry the I/O operation 
starting with the CCW in error by setting 
byte 3, bit 7 on (third operand of 
CCB=X'0001 r ). In addition, bytes 8-11 of 
the CCB must be initialized with the 
address of the first CCW in the chain each 
time the chain is executed. See Figure 
1.18 for an example using CCHAIN support. 



< 
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BEGIN 



DO 



START 





BALR 


4,0 


USING 


*,<* 


• 




• 




LA 


1,READ 


ST 


l f READCCB+8 


EXCP 


READCCB 



READCCB 
READ 



Initializes Bytes 8-11 of CCB 
with address of first CCW in 
chain each time chain is executed. 



WAIT READCCB 

BCT 3, DO 

• 

CCB SYS004,READ, X'OOOl'" 

CCW 2,DATA,X*60 , ,100 

CCW 2,DATA+100,X , 60 , ,100 

CCW 2,DATA+200,X'20 , ,100 



Indicates Command Chain Retry. 



Figure 1.18. Example Using CCHAIN Support 






CCHAIN=YES must be specified if data or 
command chaining of IBM 2495 Tape Cartridge 
Reader input is performed. 



TRACK HOLD SUPPORT (TRKHLD) 



The track hold feature allows tasks within 
the same partition or tasks outside of a 
partition to share DASD data files when 
using the direct access method or the 
sequential method of file organization. 
This track protection facility can be used 
with or without multitasking to provide 
protection between partitions. By 
definition, track protection means a DASD 
track that is being modified by some task 
in main storage is prevented from being 
accessed by another task in that partition 
or in any other partition. 

Any programs using DTFSD/SDMODXX, 
DTFIS/ISMOD, or DTFDA/DAMOD can use the 
track protection macros when performing the 
following functions. 

| • DTFIS - all functions except LOAD 

• DTFSD - updating with work files 



• DTFSD - updating without work files 

• DTFSD - other functions with work files 

• DTFDA - all functions 

The actual holding of a track is a 
combination of supervisor (PIOCS) and data 
management (LIOCS) . Track hold involves 
the actual request that a track be held and 
the request to free a track. The hold 
request is generated if you specify 
parameters in the DTFs and logic modules 
for the program (s) involved. 



Supervisor Considerations 



At system generation time, you must specify 
the number of unique tracks that can be 
held at any one time (255 maximum and 10 
minimum) . A table for the number of 
entries specified is built into the 
supervisor for storing the necessary 
information required for track protection. 

The maximum number of holds (without 
intervening frees) that a task can issue 
for a given track is 16. If more than 16 
holds are attempted, the task is canceled. 
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If the DASD channel program does not 
start with a long seek, track hold is not 
implemented. 

If multiple track search operations are 
issued, only the first specified track is 
held but it is not necessarily the same 
track on which the search is satisfied. In 
this case, the track on which the search is 
satisfied is not protected. 

If a task requests a track already held 
by another task, the requesting task is 
placed in wait state (until the track 
becomes available) . In addition, if the 
task requests a hold on the 256th unique 
track or exceeds the limit specified at 
system generation time, the requesting task 
is placed in wait state until a previously 
held track is freed. In either of these 
cases, especially in the first situation 
which has a greater chance of occurring 
than the latter, make sure that the 
following conditions do not occur. 

1. If more than one track is being held, 
it is possible for a task to put the 
entire system into wait state. This 
occurs if one task is waiting for a 
track that is already held by another 
task. In the first case, if task A 
holds track 1 on drive 1 and attempts 
to hold track 2 on drive 2 while task 
3 is holding it, task A is placed in 
wait state until task B frees that 
track. Then, if task B attempts to 
hold track 1 on drive 1, it enters the 
wait state until task A frees that 
track. Because task A is already in 
wait state, neither task ever regains 
control. If they are the only two 
tasks running in the system, the 
entire system is in wait state. 

2. A similar situation can occur if two 
or more tasks attempt to hold more 
tracks than the maximum number 
allowed. For example, assume a 
maximum of 20 unique tracks can be 
held by the system. Task A issues 15 
DASD I/O operations and task B issues 
15 DASD I/O operations (altogether 
requiring track hold for 30 unique 
tracks) . If both task A and task B 
are alternately issuing DASD I/O 
operations, then when each task issues 
its 11th track hold (at this point 
both task A and task B have held the 
maximum of 20 unique tracks) , it is 
placed into wait state. Again, 
neither will regain control, and if 
they are the only two tasks running in 
the system, the entire system is in 
wait state. 

In both examples, if the operator is not 
aware of what has occurred, he may decide 
to cancel the tasks. If the lockout is 



between two subtasks within a partition, 
the partition is canceled. If the lockout 
is between two partitions, one partition is 
canceled, its tracks are freed and the 
second partition is removed from wait 
state. 

When a task issues a free for a 
particular track, one of two conditions 
occurs : 

1. If a task has more than one hold on 
the track (16 maximum) , a counter 
associated with that track is 
decreased by one, the task retains its 
hold on the track and control is 
returned to the task issuing the free. 

2. If the task has only one hold on the 
track, the track is freed by removing 
its entry from the supervisor table. 
Any tasks waiting for the track or an 
available entry in the table are 
removed from wait state. The task 
with the highest priority gains 
control of that track or puts a hold 
on another track. 

Track hold only occurs for DOS-supported 
DASDs. Otherwise, the I/O operation is 
issued, but no track-hold function is 
involved. (This is true for any device, 
including non-DASDs . ) 

The following conditions cause 
cancelation of a task: 

1. A free was issued to a non-DASD type 
or a nonsupported DASD, 

2. Holds were not issued to that track, 

3. A task attempts to free a track held 
by another task. 

In the last case, when the main task 
detaches a subtask, any track held by that 
subtask is freed. 



LIOCS Considerations 



Track hold is only supported for DTFIS, 
DTFSD and DTFDA files. Support of the 
track hold feature requires specification 
of a HOLD parameter in both the 
DTFIS/DTFDA/DTFSD and the ISMOD/DAMOD/SDMOD 
macros. In addition, a FREE macro must be 
issued for all DTFDA or DTFIS files and for 
DTFSD work files without update. 

A maximum of 16 holds can be applied to 
one track. A free issued for a track with 
more than one hold decrements the track 
hold count, but does not release the track. 
A free issued for a track not held, 
terminates the task. 
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The track hold functions can be used in 
five specific situations: 

1. Using DTFSD for updating with work 
files (via the WRITE macro). 

2. Using DTFSD for updating without work 
files (via the PUT macro) . 

3. Using DTFSD with work files, when no 
WRITE is issued for updating. 

4. For all DTFDA files. 

| 5. For all DTFIS files except for LOAD. 

In the first two situations, the tracks 
being held are freed automatically by the 
system. For the last three situations, the 
task must issue the FREE macro instruction 
for each hold placed on a track by the READ 
macro. It should be noted that for DTFDA, 
a FREE macro need not be given when only 
WRITE macros are issued. If HOLD=YES and 
ERREXT=YES, you must issue the ERET macro 
to return to the ISAM module to free any 
held tracks. 



System Generation Guidelines 



TRKHLD=n 

The maximum number of tracks that can be 
held at one time is 255. The default is 10 
if n is an invalid parameter (nonnumeric or 
outside the range 1-255) . MPS=YES or BJF 
must be specified if TRKHLD=n. If a task 
attempts to hold an additional track after 
the maximum has been reached, the task goes 
into the wait state until a previously held 
track has been freed. 



ABNORMAL TERMINATION SUPPORT (AB) 



Abnormal termination exits are available 
for main tasks and/or subtasks, allowing 
you to gain control before an abnormal 
condition removes the task from the system. 
For example, in the abnormal termination 
routine, you can close your files. This 
function is provided by the AB operand of 
the STXIT macro. See Supervisor and I/O 
Macros listed in the Preface for detailed 



information on the format and use of the 
STXIT macro. 



STXIT Macro Considerations 



If an IT (Interval Timer) condition occurs 
while executing the OC (Operator 
Communication) or PC (Program Check) 
routines, these routines should not use the 
same save area (see Figure 1.19). 



(Routine Being | Condition Occurring | 

I Processed | -| -j -| -j 

j | AB | IT j OC | PCJ 



I 
JAB 

I 
JIT 

I 

joc 



(PC 



I 



1 I 


I | 


1 I 


H | 


1 H 


Vfj 


1 H 


H | 



I 

I I 
I 

H I 

I 

H I 

I 
T I 



X- 



E - Error message issued in foreground 
program and control returns to 
interrupted OC routine. 



H - 



V 



I - 



S - 



T - 



Condition honored. When 
processing of new routine 
completes, control returns to 
interrupted routine. 

Condition ignored for all 
partitions. 

Interrupt ignored in a background 
partition. 

Execution of the routine being 
processed is suspended and control 
is transferred to the AB routine. 

Job abnormally terminated. If AB 
routine is present and it has not 
been interrupted by itself, its 
exit is taken; otherwise, a system 
abnormal termination occurs. 



Figure 1.19. 



Processing of STXIT 
Conditions 
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When a supervisor is not generated to 
handle the requested facility, the task is 
abnormally terminated if a STXIT macro is 
used. This also applies to a program that 
requests the timer interrupt and has not 
been allocated the timer. 



when the time elapses. The SETIME, 
STXIT, and EXIT macros are used for 
this. However, only the main task of 
the partition owning the timer can 
issue these instructions. 



If an AB or PC condition occurs and 
linkage has not been established for a main 
task abnormal termination routine, the 
partition is abnormally terminated. 
However, if the AB or PC condition occurs 
in a subtask without exit linkage 
established, only the subtask is 
terminated. 

Only one main task at a time can use the 
STXIT IT macro. The partition of the main 
task is specified at system generation time 
but can be changed by the operator with the 
TIMER command. There are two distinct 
methods for using the STXIT IT macro. Only 
one method can be used at a time. 



2. The second method allows a given 
routine to be performed at timed 
intervals. The time set is a real 
time interval, and is not stopped or 
adjusted when the task using the timer 
does not have control. The SETIME, 
TECB, and WAIT macros are used. 
However, if multitasking , only one 
task within the partition can use the 
method and the WAIT on the TECB must 
appear in that task. Consideration 
should be given to the priority of the 
task assigned to process interval 
timer interrupts. Subtasks can use 
this method. 



1. The first method allows the main task 
to set the timer and enter a routine 



Figure 1.20 contains a coding example 
using STXIT support. 
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PAGE 1 


LOC 


OBJECT CODE ADDR1 


ADDR2 


STMT 


SOURCE 


STATEMENT 


FDOS CL3-5 10/30/69 


OOOOOO 






1 


STXEXAM 


START 







000000 


0520 




2 




BALR 


2*0 




000002 






3 
4 




USING 
PRINT 


*.2 

NOGEN 










5 




STXfT 


PC, PRGCK, PC SAVE 


ACTIVATE USERS PROG CHECK RTN 








11 




STXIT 


OC, COMMUN, OCSAVE 


ACTIVATE USERS OPER.COMM. RTN 








17 


GOAGAIN 


SETIME 10, TIMEBLK 


SET INTERVAL TIMER TO 10 SECONDS 








23 


PRINT 


EXCP 


CCB1 


PRINT TIMER BEGINNING MESSAGE 








27 




WAIT 


CCB1 










33 




WAIT 


TIMEBLK 


WAIT FOR TIMER INTERRUPT 








39 




EXCP 


CCB2 


PRINT TIMEOUT MESSAGE 








43 




WAIT 


CCB2 




00005A 


9263 2058 '0005A 




49 

50 


CHK 

* 


MVI 


*,99 


THIS WILL CAUSE A PROG CHECK THE 
NEXT TIME THROUGH THIS RTN 


00005E 


47F0 2014 


00016 


51 


LOOP 


B 


GOAGAIN 










52 


PRGCK 


EXCP 


CCB3 


PRINT PROGRAM CHECK MESSAGE 






(See 


Note below) 














56 




WAIT 


CCB3 










62 




EXIT 


PC 


RETURN FROM PROGRAM CHECK ROUTINE 








65 


COMMUN 


EXCP 


CCB4 


PRINT EXTERNAL INTERRUPT MESSAGE 






(See 


Note below) 














69 




WAIT 


CCB4 










75 




STXIT 


PC 


DEACTIVATE PROGRAM CHECK EXIT 








80 




STXIT 


OC 


DEACTIVATE EXTERNAL INTERRUPT EXIT 








85 




EXIT 


OC 


RETURN FROM EXTERNAL INTERRUPT RTN 








88 


DONE 


EOJ 






00009C 






91 


PCSAVE 


OS 


CL72 




0000E4 






92 

93 


OCSAVE 
TIMEBLK 


DS 
TECB 


CL72 










96 


CCB1 


CCB 


SYS000,CCW1 










107 


CCB2 


CCB 


SYS000,CCW2 










118 


CCB3 


CCB 


SYS000,CCW3 










129 


CCB4 


CCB 


SYS00CCCW4 




000170 


0900019000000064 




140 


CCW1 


CCW 


9,MSG1,X«00',100 




000178 


090001F400000064 




141 


CCW2 


CCW 


9,MSG2,X»00»,100 




000180 


0900025800000064 




142 


CCW3 


CCW 


9,MSG3,X«00«,100 




000188 


090002BC00000064 




143 


CCW4 


CCW 


9,MSG4,X«00',100 










144 


MSG1 


DC 


CLIOO'THE TIME HAS 


JUST BEEN SET TO A VALUE OF TEN SECONO 


000190 


E3C8C540E3C9D4C5 










DS,THIS LINE IS PRINTING WHILE THE TIMER IS RUNNING.' 








145 


MSG2 


DC 


CLIOO'THIS LINE HAS 


PRINTED AS A RESULT OF A TIMER INTERX 


0001F4 


E3C8C9E24003C9D5 










RUPT IE. THE TIMER VALUE HAS GONE THROUGH ZERO. 1 








146 


MSG3 


DC 


CLIOO'THIS LINE HAS 


PRINTED DUE TO THE FORCED PROGRAM CHX 


000258 


E3C8C9E240D3C9D5 










ECK AT LABEL *CHK* 


. • 








147 


MSG4 


DC 


CLIOO'AS A RESULT OF THE INTERRUPT KEY THIS PROGRAM HAS X 


0002BC 


C1E240C140D9C5E2 










GONE TO NORMAL END 


OF JOB.* 


OOOOOO 






148 




END 


STXEXAM 




000320 


0000009C 




149 






=A(PCSAVE) 




000324 


00000062 




150 






=A( PRGCK) 




000328 


OOOOOO E4 




151 






=ACOCSAVEJ 




00032C 


00000078 




152 






=A (COMMUN) 




000330 


OOOOOOOA 




153 






=A<10) ; 




000334 


00012C00 




154 






«F'76800' 




000338 


0000012C 




155 






=A(TIMEBLK) 


















PAGE 2 


LOC 


OBJECT CODE ADDR1 


ADDR2 


STMT 


SOURCE 


STATEMENT 


FDOS CL3-5 10/30/69 


00033C 


00000130 




156 






=A(CCB1) 




000340 


00000140 




157 






=A(CCB2) 




000344 


00000150 




158 






=A(CCB3) 




000348 


00000160 




159 






=A(CCB4) 











Note: If LIOCS or other CSECTS that might alter the base register are used, then a base register must be established as the first step 
in the interrupt routine. For example: 

BALR 3,0 
USING *,3 

Figure 1.20. STXIT Sample Program 
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MULTIPLE WAIT SUPPORT (WAITM) 



The multiple wait facility allows a task to 
be put into the wait state until one of a 
number of events occur before proceeding. 
Control passes to a task when one of the 
ECBs specified in the WAITM macro has been 
posted. The multiple wait facility can be 
used without specifying AP=YES. However, 
AP=YES cannot be used without WAITM=YES 
being specified. 

An Event Control Block (ECB) is a task 
communications block written by the problem 
programmer (see Figure 1.11). When a 
subtask is successfully attached, byte 2 
bits and 1 are set to 0. When the 
subtask terminates, the supervisor posts 
(sets a bit to 1) byte 2 bit of the ECB 
after processing of the abnormal 
termination routine. In addition, byte 2 
bit 1 is posted if the subtask abnormally 
terminates; that is, if task termination is 
not the result of issuing the CANCEL, 
DETACH, DUMP, or EOJ macro instructions. 
See Supervisor and I/O Macros listed in the 
Preface for more detailed information. 



Multiple Wait Considerations 



When control passes to the waiting task, 
its register 1 points to the address of the 
ECB that had byte 2, bit set. 

The user may use CCBs or TECBs in place 
of ECBs. This is possible because the 
posting of byte 2, bit occurs upon their 
event completions. BTAM/QTAM ECBs, QTAM 
control blocks, and RCBs cannot be waited 
on because their format would never satisfy 
a WAITM, i.e., byte 2, bit will never be 
posted. When waiting on only one ECB, the 
WAIT macro can be used. 

When using WAITM, a provision should be 
made for ultimate outlet if none of the 
events being waited on occur. For example, 
an abnormal ending of all the tasks on 
which a multiple wait was dependent would 
never allow the multiple wait to be 
satisfied. 

The user may specify a preferred event. 
Consider the following example: 

WAITM ECBA, ECBB, ECBC. 

ECBA is considered the preferred event 
because it appears first on the list. For 
the same reason, ECBB is considered the 



second most preferable event. The user may 
use this to his advantage in task 
synchronization. The system checks the 
ECBs in the order written in the WAITM 
macro. 



DASD FILE PROTECT SUPPORT (DASDFP) 



The DASD file protect facility provides 
read/write file protection for DASDs. All 
I seeks issued by a problem program are 
monitored by the supervisor to ensure that 
the seeks do not stray outside of limits 
that were validated at file open time. 
(This could occur during the loading of a 
direct access file.) DASDFP functions on a 
cylinder basis for the 2311, 2314, and 
2319, and on a strip basis on the 2321. 
DASDFP routines are not executed when the 
current PSW has a storage protect key of 
zero. This occurs for supervisor, job 
control, and transient routines ($$A, $$B, 
$$R). 



Mode of Operation 



Job control or the foreground initiator 
reads the DLBL/EXTENT (or VOL/DLAB/XTENT) 
control commands or statements from the 
input job stream. This information is 
reformatted and written on the label 
information cylinder on SYSRES as one or 
more DASD records. Each of these DASD 
records is preceded by a key created from 
the filename (DTF name) entry in the 
DLBL/VOL command or statement. 

When the problem program opens the file 
(DTF) , the OPEN transient routine extracts 
an 8-byte alphameric constant from the 
generated DTF table. This constant is 
called the filename, and is an exact 
replica of the DTF name. 

The OPEN transient routine searches the 
label information cylinder on SYSRES to 
find a key equal to this DTF filename 
constant. When it finds a match, it reads 
the data portion of this job control DASD 
record into the label save area in main 
storage. 

The extent information is extracted from 
this job control DASD record, and is stored 
I in the JIB table. A 2311/2314/2319 extent 
requires one JIB entry; a 2321 extent 
requires two JIB entries (see Figures 1.21 
and 1.22). 
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Number in 
Class List 
(NICL) 



LUB Table 



First 

Class List 
(FICL) 




BG 

System 

LUBs 

BG 

Programmer 

LUBs 


-n. 


F2 

System 

LUBs 

F2 

Programmer 

LUBs 


F1 

System 

LUBs 

F1 

Programmer 

LUBs 



SYS 



BG 



F2 



f F1 



LUB Table for any Partition 
SYSRDR 



© 



)SYSIPT 
JSYSPCH 



, 



SYSLST 
(D SYSLOG 
SYSLNK 
SYSRES 
SYSSLB 
SYSRLB 
(D SYSUSE 
SYSREC 
SYS000 
SYS001 
SYS002 
SYS003 
SYS004 

© SYS221 
(D SYSCLB 



f\, 



- Points to first PUB 
1 - Points to second PUB 
000 001 0- Points to third PUB 

J* ^ 



1 1 1 1 1 1 1 - Ignore — ~~ 

1 1 1 1 1 1 1 1 - Null Pointer, the LUB is Unassigned 

When a logical unit is assigned, the system inserts a 
pointer to the PUB for the physical device specified. 



: Format of Any LUB \ 



ByteO 


Bytel 


PUB Pointer 


JIB Pointer 



JIB Index (Multiply by 4 = displacement into JIB Table) or X'FF' = Null 
Pointer, no JIB for this LUB 

A LUB has a JIB pointer when: 

1. The logical unit is temporarily assigned. 

2. The logical unit assignment is alternate (ALT). 

3. A DASD file (except a system I/O file on disk) is opened. 



F1 






F2 






BG 







Bytes 76 and 77 (X'4C - '4D') of the communications region contain the address of the LUB table entry. 
Label LUBTAB identifies the first byte of the table. 



© When in Single Program Initiation mode (Foreground 1 or 2): Must be unit record device and can be referenced by the program. 

(D When in Single Program Initiation mode (Foreground 1 or 2): Can be referenced by the program. 

(D SYSUSE may be called SYSCTL in error recovery messages. 

(5) The maximum number of programmer logical units in the system is 222 if MPS = BJF, or 244 if MPS = YES or NO. 

© The SYSCLB (Private Core Image Library) LUB entry functions the same as other LUB entries, but is not part of the LUB Table. To locate the SYSCLB LUB in supervisor perform the 
following steps: 

1. Divide the PIK by 8. 

2. Subtract the result in step 1 from the address of the PIB extension block. 

3. If option AP = YES, the result of step 2 is the location of SYSCLB LUB. If option AP = NO, add 16 (for the all-bound PIBX) to the result of step 2. 



-J 



JIB Table 



JIB 1 


JIB2 


JIB 3 


JIB4 


JIB 5 


JIB6 



Number (length of JIB table) 
determined at supervisor generation 



Note: Two JIBs are required for a 2321 extent; one for lower 
limit and one for upper limit. The lower limit defining 
JIB must be chained to the upper limit defining JIB. 
Byte 1 of this type JIB contains the subcell number 
times 10 plus the strip number in binary. 






1 


2 


3 



Type of Entry 



Stored standard 
assignment 



Alternate 
assignment 



/7s 231 1/2314/ 
W2319 Extent 



© 2321 Extent 



LUB entry of stored 
standard assignment 
(PUB and JIB pointers) 



PUB pointer 
of alternate 
assignment 



X'00' 



C L C L C ,H C H © 



Bi Bi C| C 
B H B H C H C H 



I r L .. ® 



(Y) Only when file -protect on DASD 

\2) Lower Cylinder 
Upper Cylinder 

\2) Cell or combined sub -cell and strip 



Flag Type 


Bit 


Meaning if Bit = 1 


Contents 





Stored standard assignment 


1 


Alternate assignment 


2 


2311/2314/2319 Extent 


3 


2321 Extent 


4 


Standard assignment for DASD Extent 


Ownership 


5 


Background 


6 


Foreground 1 


7 


Foreground 2 



Chain Byte . 
Contains the displace- 
ment index of the next 
JIB. A hexadecimal 
'FF' defines the end of 
the chain. 



Bytes 68-69 (X'44' - '45') of the communications region contain the address 
of the JIB table entry. Label JIBTAB identifies the first byte of the table. 



Figure 1.22. Job Information Block (JIB) Table 
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An EXTENT /VOL command or statement names 
the symbolic unit containing the extent. 
The $$BOFLPT OPEN transient stores each 
extent into a JIB entry that is related or 
linked to a specific symbolic unit. 



When the problem program requests an I/O 
operation on DASD, the supervisor extracts 
the symbolic unit and the seek channel 
command word (CCW) from the command control 
block (CCB). The current DASD seek address 
is compared to the extent limits stored in 
the JIB table for this specific symbolic 
unit. If the DASD seek address falls 
outside the range of extents, the job is 
canceled. 

For a 2311/2314/2319 extent, the upper 
and lower cylinder numbers comprise the 
protection boundaries for the named 
symbolic unit. A 2321 is only protected on 
strip boundaries. 

Note : This is a programmed check to 
determine if the problem program is trying 
to access data outside the allowed cylinder 
or strip limits. 

Next, the supervisor builds and executes 
a small channel program containing three 
commands: a seek that is identical to the 
problem program seek, a Set File Mask that 
prevents any other long seeks (X*07*) from 
being executed, and a TIC that transfers 
control to the command following the 
problem program's seek (see Figure 1.23). 

Note : This is a hardware check to prevent 
the problem program* s channel from moving 
the read/write head outside the cylinder or 
strip limits that were validated by the 
programmed check. 

DASDFP provides file protection on the 
basis of symbolic unit. It does not 
provide protection by access method, file, 
or DTF. However, if each DTF in a problem 
program is assigned to a different symbolic 
unit, file protection can prevent one DTF 
from accessing the data belonging to 
another DTF. 



Also, DASDFP does not prevent file 
contention between partitions. Thus, more 
than one partition may access the same file 
at the same time (and both partitions may 
attempt to update the same record 
simultaneously) . When using DASDFP, follow 
these guidelines: 



1. For complete protection, files should 
begin and end on cylinder /strip 
boundaries . 

2. File protection is ensured only if the 
DASD labels involved are unexpired. 

3. In any one program, each DTF should 
use a different symbolic unit, even if 
the files reside on the same physical 
volume. 

4. The system residence file must reside 
on a protected channel. If it does 
not reside on a protected channel, you 
will not be able to IPL your system. 



System Generation Guidelines 



DASDFP= 



NO 

(n,n,(2311))( 
<2314> 
(232l) 



n, n specifies the range of channels on 
which DASD may be attached. If either 2311 

| or 2314/2319 is specified, protection for 
both is provided. If 2321 is specified, 

| 2311, 2314, 2319, and 2321 are supported. 

If the parameter for a 2311, 2314 or 
| 2321 is omitted, both 2311 and 2314/2319 
protection is assumed. 

Example: 

DASDFP= (1,3, 2321) 

Protection is available on channels 1, 2, 
I and 3 for 2321s, 2311s, and 2314s/2319s. 
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Start I/O 



DASD Device 



YES 



Check 
1st CCW for 
Long Seek 

X'07' 



NOTE1 



YES 



! Seek 
With in 
Limits 



NOTE2 



YES 



Move Seek 
Address 
to CCW in 
Supervisor 



NO 



Normal 
Start 



NO 



NO 



— I 

Error 



NO 



Check 
2nd CCW 
! for TIC 

I YES 



Move Address of 

Users 2nd CCW 
to TIC CCW in 
Supervisor 



Move TIC Address 
from Users 2nd 
CCW to TIC CCW 
in Supervisor 



NOTE3 [ 

EXEC CCW Chain 
in Supervisor 



NOTE1. Check JIB for this file. 

NOTE2. Supervisor moves user's seek address to a CCW chain in supervisor. 

NOTE3. The following CCW's are in the supervisor, one set for each channel that has DASD file protect. 
07, User seek address, X 1 60', 6 
31, File mask, X'40',1 
08, User CCW (2nd or TIC address from 2nd),X'40',0 



Figure 1.23. DASD File Protect Logic Flow 



SYSTEM FILES ON DISK SUPPORT (SYSFIL) 



In systems with at least 24K bytes of main 
storage, the system logical units SYSRDR, 
SYSIPT, SYSIN, SYSLST and/or SYSPCH may be 
| assigned to an extent on 2311 or 2314/2319 
disk storage. 

The system files when used on disk are 
supported by use of the ASSGN and CLOSE job 
control statements, and by the supervisor 
channel scheduler routines. 

Job control, via the standard ASSGN 
statement, opens the file and initializes 



the disk information block (DIB table) 
within the supervisor. Figure 1.24 shows 
the DIB table (also, see Figure 1.21). 



Each time a problem program requests I/O 
on a system logical unit, the supervisor 
checks the DIB table for a valid seek 
address. (Note that the job information 
block is not used for system files on 
disk) . After each successful access to the 
file, the supervisor updates the current 
address field in the affected DIB. 
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SYSLNK 

SYSIN 

SYSPCH 

SYSLST 

Number 
of Bytes 

KEY: Current Address: The next address to be used (for both input and output). 



End Address 

R 

U.L 

L. L. 

R.C. 



P 
KDD 



The last address within the limits of the extent. 

Maximum number of records per track. 

Upper head limit 

Lower head limit 

Record Count- residual capacity for beginning of operator notification. 

This is set at system generation time with the SYSFIL parameter, or after 

IPL with the SET statement (RCLST and /or RCPCH operands). A warning 

message is issued by job control after end -of- job step when the minimum 

number of remaining records has been reached or exceeded during the 

previous job. 

Starting cylinder of private core image library, if assigned. 

Key and data length for the symbolic device. 



KDD for SYSIN = X'000050' 
KDD for SYSPCH = X'000051 ' 
KDD for SYSLST = X'OOOO^ 1 

Bytes 96 and 97 (X'60 1 - '61') of the communications region contain the address of the SYSLNK entry. 
Label DSKPOS identifies the first byte of the table. 

Figure 1.24. Disk Information Block (DIB) Table 



When a problem program issues an open to 
a system file that is currently assigned to 
disk, the LIOCS open routines transfer the 
extent information to the DTF table from 
the DIB instead of from the file label in 
the volume table of contents. This causes 
the current address field in the DIB to be 
used as the beginning extent for the DTF of 
the file being opened. 



Considerations When Using System Files on 
Disk 



The system logical units of SYSIPT, 
SYSRDR, SYSIN (SYSIN is both SYSIPT 
and SYSRDR), SYSPCH, and SYSLST can be 
assigned to disk for any batched job 
partition. 



) 



When a problem program closes a system 
file that is assigned to disk, the LIOCS 
close routine posts the file closed and 
does not disturb the DIB. 



Job control, via the CLOSE statement, 
closes the system files on disk and 
deactivates the DIB. 



2. Record lengths for these assignments 
are: 



•80 for SYSRDR 

• 80 or 81 for SYSIPT on the IBM 231J. 
(80 for the IBM 2314) 

•121 for SYSLST 

•81 for SYSPCH 
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3. The creation of files for use as 
system input, and the printing or 
punching of system output files is 
done by user-written programs. 
(Utility programs are available to 
simplify this.) 

4. Predefined symbolic filenames have 
been established for all system files 
that can be assigned to disk. The 
filenames (used in the DLBL statement 
and associated with the SYSxxx entry 
of the accompanying EXTENT statement) 
are IJSYSIN for SYSRDR, SYSIPT, or 
SYSIN; IJSYSPH for SYSPCH; IJSYSLS for 
SYSLST. 

5. When SYSRDR and SYSIPT are both 
assigned to disk, they must reside in 
the same extent and be referred to as 
SYSIN. The filename specified in the 
DLBL/VOL command or statement must be 
IJSYSIN. 

6. Because SYSPCH and SYSLST have 
different size records, SYSOUT cannot 
be assigned to disk. 

7. Job control issues operator warning 
messages when the area assigned to 
disk approaches a predefined residual 
capacity. 

8. The residual capacity for operator 
warning is established at supervisor 
generation time with the FOPT macro 
(SYSFIL parameter) . These values can 
be changed after IPL by the SET job 
control command (RCLST, RCPCH 
operands) . 



System Generation Guidelines 



NO 



SYSFIL= { (/231lU,n lf n a ]) 
|2314/ 



Specification of either 2311 or 2314 gives 
support for 2311/2314/2319. If MPS=BJF in 
the SUPVR macro, this parameter supports 
foreground logical units when running in 
batched mode. If the emulator program 
parameter SYS 10= 222 or SYSI0=333 is 
indicated, a value must be specified for 
SYSFIL. 

n ± = residual capacity for beginning of 

operator notification when SYSLST is 
assigned to disk. 100<ni<65535. If 
n x is omitted, 1000 is assumed. 

n 2 = residual capacity for beginning of 

operator notification when SYSPCH is 
assigned to disk. 100<n 2 <65535. If 
n a is omitted, 1000 is assumed. 



PRIVATE CORE IMAGE LIBRARIES 



The ability to create and maintain private 
core image libraries provides the single 
partition (no MPS or BJF) and the multiple 
partition users with the ability to 
maintain all the installation programs in 
core image format. It also augments the 
multiprogramming facility. A private core 
image library may reside (starting on any 
cylinder boundary) on any volume. The 
organization of the first ten tracks and 
the private core image directory and 
library is similar to that portion of the 
system residence volume from cylinder 0, up 
to and including the core image library 
itself (see Figure 1.1). 

The areas containing the bootstrap 
records, volume labels, system directory 
records 2-4, and the IPL loader program are 
formatted but unused in a private core 
image library. The system work area and 
all directories (transient, open, etc) are 
formatted, used, and maintained for a 
private core image library in the same 
manner as these areas are used and 
maintained for the system core image 
library. Multiple private core image 
libraries may reside on one volume or they 
may be created on separate volumes. 

A private core image library may be 
assigned to any partition. Output from the 
linkage editor may be placed in a private 
core image library. Librarian functions 
are available to create and maintain this 
type of library. 

If a catalog function is attempted in 
the foreground partition, the supervisor 
will be cataloged in the private core image 
library, and the IPL routine cannot access 
a private core image library. 



System Considerations 



In a disk system supporting both 
batched- job foreground and private core 
image libraries, several choices are 
available to the user as to the partition 
in which his programs are to be link-edited 
and in which they are to execute. A 
program may be: 

1. Link- edited in the background to 
execute within the background and 
placed in the system core image 
library or a private core image 
library. 

2. Link-edited in the background to 
execute within a foreground partition 
and placed in the system core image 



< 



76 DOS System Programmer's Guide 



library or a private core image 
library. 

3. Link-edited in a foreground partition 
to execute within the background and 
placed in a private core image 
library, which will be assigned to the 
background at execute time. 

4. Link-edited in a foreground partition 
to execute within that foreground 
partition and placed in a private core 
image library assigned to that 
partition . 

User programs written in Assembler should 
avoid the use of Y-type address constants 
if they are to properly execute within a 
foreground partition. Most IBM-supplied 
language translators can execute in a 
batched- job foreground partition, providing 
enough main storage is available in which 
to execute the translator. For a list of 
IBM- supplied programs that can execute in 
the foreground, refer to DOS Concepts and 
Facilities listed in the Preface . 

The selection of both the batched- job 
foreground and private core image library 
options provides the most efficient 
multiprogramming environment. The 
following is a suggested procedure for 
creating such an environment. Figure 1.25 
shows a private library dedicated to each 
partition. Figure 1.26 shows the use of 
private libraries in a single partition 
environment. 

1. For maximum efficiency, the system 
core image library can be reserved for 
system program phases. 

2. Link-edit the assembler and other 
language translators in the background 
and place them in a private core image 
library. See Note . 

3. Repeat this process in each desired 
foreground partition, cataloging the 
output from the linkage editor to a 
private core image library assigned to 
that foreground partition. 

Some language translators require a 
partition size of more than 10K to 
execute . 

4. Self -relocating programs may be 
cataloged in the system core image 
library or a private core image 
library. 



5. 



If a non-self-relocating program is to 
be run only in one partition it should 
be link-edited and cataloged in a 
private core image library that will 
be assigned to that partition. See 
Note. 



If a non-self-relocating program is to 
be run in more than one partition, it 
should be link-edited and cataloged to 
the core image library for each 
partition . 



Note: 



If it is not desired to 



dedicate a private core- image library 
to the background partition, these 
programs must be placed in the system 
core image library. 



In the environment just created, it is 
possible to execute a compile, link edit, 
and go job in any partition. To execute 
such a job in a foreground partition, a 
private core image library must be assigned 
to that partition. When executing the 
linkage editor in a foreground partition, 
output must be placed in a private core 
image library. When executing in the 
background partition, output from the 
linkage editor can be permanently placed in 
either the system core image library or a 
private core image library, if assigned. 



A unique SYSLNK, as well as other work 
files (for example, SYS001, SYS002) , is 
required for each partition. If the 
language translators are to execute 
concurrently, then each work file must be 
uniquely identified. For example: 

// DLBL IJSYSLN, ■ DOS. BG. SYSLNK* 
// EXTENT , , , , 10, 200 
// DLBL IJSYS01, 'DOS.BG.SYS001* 
// EXTENT ,,,,410,200 



// DLBL I JSYSLN,* DOS. Fl. SYSLNK* 
// EXTENT , , , , 210 , 200 



If the SYSLNK for each partition is 
assigned to a different drive, no unique 
identification is necessary. Figure 1.27 
illustrates these two cases. 
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SUPVR 



BG 



F2 



Fl 



//JOBCOMPIL1, LINK- 
EDIT-EXEC 



Fl SYSIN 




// EXEC FCOBOL 



//OPTION LINK 



ASSGN SYSCLB,X'233' 
OPEN FILE 



//DLBLIJSYSCL/FICIL' 



| Figure 1.25. Example of Dedicated PCIL in a Multiple Partition Environment 
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|P£ "^^r^^- | 



SUPVR 



BG 




>- 



^ Space ^ 




CUU =234 



CUU =233 




Accounts 
Receivable 
Data File 




fV/EXEC INV078 



/aSSGN SYSCLB, X'234' 
fV/PLBL IJSYSCL, 'INVENTORY' 



/7/JOB INVENTRY 
fosSGN SYSCLB, UA 
f/& 
(V/ EXEC PAY 103 



fV/EXEC PAY 092 
f^ASSGN SYSCLB, X'233' OPEN FILE 



/V/DLBL IJSYSCL, 'PAYROLL' 
///JOB PAYROLL 



| Figure 1.26. Example of PCIL in a Single Partition Environment 
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I Figure 1. 27. Identification of SYSLNK Files 



80 DOS System Programmer's Guide 



In a batched- job multiprogramming 
environment the assembler and linkage 
editor functions can execute simultaneously 
in different partitions, each with its own 
assigned private core image library. 
Non-self -relocating programs are not 
limited to execute in only one partition 
because a version may be link edited for 
each partition and stored in the core image 
library for that partition. 

Note that in fetching or loading a phase 
into main storage, if a private core image 
library is assigned, it is searched first. 
If the phase is not found in the private 
core image library, the system core image 
library is searched. The one exception to 
this sequence is for $ and $$ phases, in 
which case the system core image library is 
searched first. 

The multiprogramming system just 
described requires a minimum of 32K of 
positions of main storage. 



System Generation Guidelines 



PCIL=/NO \ 
\YESJ 

To specify supervisor support for private 
core image libraries, the PCIL=YES keyword 
parameter must be included in the FOPT 
macro. If PCIL=YES is specified and MPS-NO 
or MPS=YES, private core image library 
partition support is provided for the 
background only. 



JOB ACCOUNTING INTERFACE SUPPORT 



The Job Accounting Interface facility 
provides job step and job information that 
you can use for charging system use, 
supervising system operation, planning new 
applications, etc. 

When this option is selected (JA=YES or 
ni,n 2 ,n 3 ), system functions build 
accounting tables in the supervisor and 
accumulate accounting information. (See 
Figure 1.28 for the job accounting table.) 
To utilize this information, the user must 
write a self-relocating routine to store or 
print the desired portions of the table. 
This routine must be cataloged in the core 
image library under the name $JOBACCT. 
One user job accounting table is built for 
each partition when MPS=BJF; otherwise, 
only one table is reserved (for the 
background) . When the system is running in 
the Single Program Inititation (SPI) mode, 
tables for the foreground partitions cannot 
be accessed. 



Programming Considerations 



If the user I/O routine ($JOBACCT) is 
written using LIOCS with label processing 
(for example, standard label tapes, DTFDA, 
or DTFPH with MOUNTED=ALL) , the JALIOCS 
parameter also must be specified. This 
parameter is used to reserve a user save 
area and a label area in the supervisor. 
The label area replaces the one normally 
used by LIOCS label processing routines. 



$JOBACCT can be as large as 4,096 bytes, 
but may use overlay loading if more storage 
is needed. For more efficient loading it 
should not exceed one core image library 
block (1728 bytes on an IBM 2311, or 1688 
bytes on an IBM 2314/2319) . With the 
one-block length, only one LOAD is required 
to get the routine into main storage. 



Because $JOBACCT is called in at the end 
of each job step, it should only perform 
data gathering and recording, but not data 
reduction and formatting if additional 
system overhead is to be held to a minimum. 
Overhead depends largely upon the 
efficiency of $JOBACCT. The optional SIO 
accounting (JA=nj.,n2,n 3 ) also causes 
additional overhead. 

LIOCS uses registers 13-15. If $JOBACCT 
needs any of these registers when any LIOCS 
function has been performed, save and 
restore the desire registers (register 14 
should always be saved when using LIOCS 
because it is necessary to return to job 
control via BR 14) . 

If $JOBACCT uses LIOCS, it should save 
at least part of the DTF information 
(status switches, extent information, 
pointers) in the user save area- If more 
than one DTF is used, information from each 
should be saved. The user save area may be 
used to save any type of information as 
well as accumulate step to step statistics 
for end of job accounting. This 
accumulation reduces the rate of scheduled 
output records caused by writing a step 
accounting record for each job step. The 
user save area is not accessed by system 
functions . 

If an error occurs that causes $JOBACCT 
to be canceled, $JOBACCT is not called 
again until the system is re-IPLed. "JOB 
ACCT" appears in the cancel message, and 
the problem program name appears in the EOJ 
message. The STXIT option also may be used 
to inform the operator that an error 
occured in $JOBACCT rather than in the 
problem program. The job in that partition 
is terminated and normal processing 
continues with the next job. 
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The system passes registers 11-15 to the 
user ' s I/O routine ( $ JOBACCT) . These 
registers contain the following 
information: 

• Register 11: length of the job 
accounting table. Each table may vary 
in length according to the number of 
SIO counts specified at system 
generation time. 

• Register 12: base register for 
$JOBACCT (this eliminates the need for 
the user to load the base register) ; 



• Register 13: 
area; 



address of the user save 



• Register 14: link register ($JOBACCT 
must exit via BR 14 to return to job 
control) ; 

• Register 15: address of the 
partition's job accounting table. 

Because some of the job step information 
(see fields 4, 5, and 10-16 in Figure 1.28) 
is cleared in the step-to-step transition, 
job control calls $ JOBACCT at the end of 
each step. If $ JOBACCT does not save or 
accumulate this information, it is lost. 



system Generation Guidelines 



( M2 
JA=< YES 

((ni,n 2 ,n 3 ) 



Specification of either YES or (n i# n 2r n 3 ) 
gives Job Accounting Interface support. If 
MPS=BJF (in the SUPVR macro) Job Accounting 
Interface is supported for all partitions. 
(The foreground job accounting tables 
cannot be accessed when running in the SPI 
mode . ) 

Specification of (n if n 2f n 3 ) gives the 
additional support of SIO accounting. The 
value of each n may range from 0-255 and 
indicates the number of devices available 
for SIO accounting for each partition (BG, 
F2, and Fl, respectively). These numbers 
are independent of the system generation 



option of the number of devices attached to 
the system. If more I/O devices are 
accessed than the number specified for that 
partition, SIO accounting for the 
additional devices will not be performed. 



JALIOCS=<NO 

(s, I ) 



No indicates that no special LIOCS support 
is required. Specification of (s, t ) 
indicates that a user save area and a label 
area are to be reserved. 

s is the decimal number of bytes to be 
reserved for the user save area (located in 
the supervisor) . This save area may be 
used to save DTF information or for any 
other purpose desired by the user. The 
system does not access this area. (The 
address of the save area is available in 
register 13 when $JOBACCT is called. ) The 
range of valid s is 0-1024, with a default 
of 16. 

I is the decimal number of bytes 
needed for a label area. This label area 
replaces the one normally used by LIOCS 
label processing. It is required when 
$ JOBACCT uses LIOCS for such things as 
standard tape labels, DTFDA, and DTFPH with 
MOUNTED=ALL. The valid range of I is 
0-224 with a default of zero. The value 
that is substituted for I is normally the 
number of bytes that would be allocated by 
a given parameter on the LBLTYP statement. 
See DOS System Control and Service listed 
in the Preface , to determine the number of 
bytes allocated for any given LBLTYP 
statement. 

If the JA parameter is specified and 
JALIOCS is not. Job Accounting Interface is 
generated but no alternate label area is 
reserved (16 bytes are reserved for the 
save area) . The routine $JOBACCT must then 
use a device or method that does not 
require LIOCS label processing. If the JA 
parameter is not specified, the JALIOCS 
parameter is ignored. 

When the JA parameter is included, timer 
support is automatically included. If the 
CPU is not equipped with a timer, or if the 
timer is disabled, time fields in the 
accounting table will not be meaningful. 
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72- 



16 



Job Name. 8-byte character string taken fron 
JOB card. 



User Information. 16 characters of information 
taken from the JOB card. 



Partition ID. BG, F2, or Fl, 



Cancel Code. 



Type of Record. S = job step; L=last step of job. 



Date, mm/dd/yy or dd/mm/yy depending on 
supervisor option. 



Start Time. OhhmmssF, where h = hours, m = minutes, 
s = seconds, F is a sign (in packed decimal format). 



Stop Time, zeros except in last record, which has 
job stop time (in same format as start time). 



Reserved . 



Phase Name. 8-byte character string taken from the 
EXEC card. 



High Core: Hex address of uppermost byte of any 
program fetched or loaded (taken from the communi- 
cations region). 



CPU Time. 4 binary bytes given in 300ths of a second. 
Time is calculated from exit of the user- written 
routine called during job control to next entry of the 
routine. Time used by the user- written output routine 
is charged to overhead of the next record . 



Overhead Time. 4 binary bytes given in 300ths of a 
second. Includes time taken by functions that 
cannot be charged readily to one partition (such as 
attention routine and error recovery). System 
overhead time is divided by the number of active 
batch partitions and recorded in each accounting 
table. 



All Bound Time. 4 binary bytes in 300ths of a second. 
This is the time the system is in the wait state divided 
by the number of partitions running. 



SIO Tables. Variable number of bytes. Six bytes are 
reserved for each device specified in the JA param- 
eter. First two bytes are X'Ocuu', next four are hex 
count of SIOs for job step. Unused entries contain 
X'10 1 followed by five bytes of zeros. Stacker select 
commands for MICR devices are not counted. Error 
recovery SIOs are not charged to the Job Accounting 
Table. Devices are added to the table as they are 
used. 



Overflow. Normally X'20'. Set to X'30 1 if more 
devices are used than set by the JA parameter at 
system generation time. 



Note: The difference between Start and Stop times will not necessarily 

equal the sum of CPU, All Bound, and Overhead times. All Bound 
and Overhead times will vary, depending on the number of active 
partitions and the type of partition activity. CPU time is accurate 
for each partition, but it may not be reproducible (recreatible). 
That is, the same job being executed under different system con- 
ditions (varying number of active partitions, logical transient 
availability, etc) may show differences in CPU time. 



v Cancel 


%XW&:C-s-.<S^%s*&^ 


\ Code 


Cause \ 




(hex) 






10 


Normal EOJ 




17 


Program Request. Same as 23 but causes dump 
because subtasks were attached when maintask 
issued CANCEL macro. 




18 


Eliminates cancel message when maintask issues 
DUMP macro with subtasks attached. 




19— 


I/O operator option. 




1A — 


I/O error. 




IB-" 


Channel failure. 




1C 


CANCEL ALL macro issued. 




ID 


Maintask termination. 




IE— 


Unknown ENQ requestor. 




IF- 


CPU failure. 




20 


Program check. 




21- 


Illegal SVC. 




22 


Phase not found. 




23 


Program request. 




24— 


Operator intervention. 




25— 


Invalid address or insufficient core allocation 
to partition. 




26 


SYSxxx not assigned (unassigned LUB code) . 




27 


Undefined logical unit (invalid LUB code in 
CCB). 




28 


QTAM cancel in progress. 




30 


Read past /& on SYSRDR or SYSIPT. 




31 


I/O error queue overflow (error queue 
overflow or no CHANQ entry available for ERP) . 




32 


Invalid DASD address (disk). 




33 


No long seek (disk). 




34-- 


I/O error during fetch (irrecoverable I/O 
error during fetch of non- $ phase). 




35 


Job control open failure. 




40 


Load $$BEOJ . 




80 


Cancel occurred in Logical Transient Area (LTA). 




FF 


Unrecognized cancel code, or, if the system 
is placed in the wait state and no further 
processing is done by the terminator, supervisor 
catalog failure. 



| Figure 1.28. Job Accounting Table 
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ALLOC Macro 



value generated is 5 and the maximum value 
is 255. 



Fl=nK, F2=nK 



This macro is optional. It specifies the 
partition sizes for the foreground areas. 
Because the foreground partition is storage 
protected, n must be a multiple of 2. The 
allocation of the foreground partitions is 
dependent upon core size and the fact that 
the background area must be at least 10K. 
(14K is required if the 14K variants are 
used in the Assembler or COBOL. ) The 
allocation for the foreground partition may 
be altered after supervisor generation by 
the use of the ALLOC control statement. 



System Considerations 



If the system residence pack is to be used 
on more than one system, specify the 
partition sizes for the smallest system in 
the ALLOC statement. Then, if the system 
residence pack is used on a system with a 
larger amount of main storage available, 
the partition boundaries can be changed by 
submitting an ALLOC statement after IPL has 
been completed. 



IOTAB Macro 



JOB INFORMATION BLOCK (JIB) 



CHANNEL QUEUE (CHANQ) 



CHANQ= iS or 6+CBF \ 

The channel queue (CHANQ) table is used by 
the supervisor to schedule I/O operations . 
The table consists of four byte entries 
containing a pointer to the next CHANQ 
entry for that device followed by the CCB 
address of the specified device. The n 
parameter specifies the number of entries 
in the channel queue table. The minimum 
value generated is 6. If the assumed value 
is taken and the console buffering (CBF) 
option is specified, the assumed value is 
six more than the CBF value. The maximum 
number of CHANQ entries that can be 
specified is 255. Figure 1.29 shows the 
CHANQ table. 



Determining Size of the CHANQ 



When determining the size of the CHANQ at 
system generation time consider the 
following: 

1. In a teleprocessing environment with 
many lines and terminals, the size of 
the CHANQ could become exceedingly 
large (see the following discussion 
and Note 1) . 



The job information block (JIB) table 
(Figure 1.22) is used by the supervisor to 
store the permanent LUB assignments for the 
duration of a temporary assignment 
(// ASSGN) . It is also used to store 
extent information if the DASDFP feature is 
implemented, and to handle alternate 
assignments. 

One JIB entry is required for each 
logical unit temporarily reassigned by a 
// ASSGN statement. One JIB is required 
for each alternate logical unit assignment. 
One JIB is required for each open 
2311/2314/2319 extent with the DASD file 
protect feature (except for system 
input/output extents) . Two JIBs are 
required for each open 2321 extent with the 
OASD file protect feature. The minimum 



2. If multifile volumes are used on the 
system, one CHANQ entry is required 
for each file being accessed at the 
same time. 

3. When the supervisor finishes with an 
entry in the queue, this entry can be 
used for some other device. Thus, the 
first entries in the CHANQ are most 
often used while the entries near the 
end of the table are seldom used. 

4. If there are not enough entries 
specified in the CHANQ (the last entry 
in the table is in use when another 
I/O request is made), the requesting 
task or partition must wait in a 
compute loop until an entry is free to 
allow scheduling of the I/O operation. 
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The free list pointer contains a displacement index to a free list entry within the channel queue. 
The free list is a group of entries that function in essentially the same manner as a device queue. 
When the free list pointer contains a hexadecimal FF, it indicates that no more free list entries 
are available. 

The first byte of the channel queue entry (chain byte) contains a pointer (displacement index) 
to the next channel queue entry for that device. A hexadecimal FF indicates the last channel 
queue entry for that device. New requests on a given device are queued at the end of a given 
device queue. 

CCB address for the specified device. 

A pointer (displacement index) to the entire LUB table identifying the logical unit making the 
I/O request. This is doubled to get the actual displacement into the full LUB table. 

Contains a pointer (displacement index) to the first channel queue entry for a specific device 
(Figure 19). 

Contains a code identifying the program making the I/O request. The one- byte entry is called 
a RID (Requestor Identification). The RID indicates what program the CCB belongs to. The 
RID is in the form X'nk'. 

n = user-storage protection key (supervisor = 0, BG = 1, F2 = 2, FT = 3). 
k = for all user requests and all supervisor CCBs, where n = 0. 
k = 1 for supervisor CCBs to SYSLOG that bypass ID prefix, 
k = 2 for a fetch CCB. 
nk = FF for any unused channel queue entries. 

Contains X'FF 1 if the LUB is nonsystem class, or contains the displacement index within the 
partition LUB if it is a system class LUB. 



I H I Contains X'FF', or the displacement into the PIB table for the PIB of the task requesting I/O. 

Bytes 108-109 (X'6C -'6D') of the communications region contain the address of the LUBID Table. Label LUBIDTAB identifies the first 
byte of the table. Bytes 98-101 (X'62 1 - '63') of the communications region contain the address of the Error Recovery Block (ERRBLOC); 
ERRBLOC +6 bytes is the address of the channel queue table (CHANQ). The addresses of the other tables are not at fixed locations. 
They can be found in the program listing cross-reference by using the labels REQIDTAB, LUBDSPTB, and TSKIDTAB. CHANQ can also 
be found in this way. 

Figure 1.29. CHANQ, LUBID, REQID, LUBDSP, and TKREQID Tables 
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The following two approaches are 
presented as an aid in determining the 
number of CHANQ entries to specify. 

1. Using the total number of devices on 
the system as a base, add one to that 
value for each file (other than the 
first) on any DASD. For example: 



the start of the table at X , 2D24 , # the 
contents of the CHANQ after an IPL 
would be: 



Device 

2540 Card Reader 

(X'OOC) 



Number of CHANQ 
CHANQ Files After Entry 
Entries First File Total 



2540 Card Punch 


1 





1 


(X'OOD*) 








1403 Printer 


1 





1 


(X'OOE*) 








1052 Printer- 








Keyboard (X'OlF') 


1 





1 


2311 Disk Drive 


1 


1 


2 


(X'190*) 








2311 Disk Drive 


1 


1 


2 


(X'191*) 








2311 Disk Drive 


1 


1 


2 


(X'192*) 









2. 



3. 



4. 



TOTAL 10 



Generate your system using 10 as a 
value for the CHANQ parameter. 

Run your worst case or heaviest 
workload against the system. Then 
take a storage dump. 

Determine how many of the channel 
queue entries were used in the worst 
case environment. 

As an aid in determining the number 
of entries used, let us examine the 
contents .of the CHANQ for the same 
system after IPL and after running our 
worse case workload. First, assuming 



Hex 
Location 

2D24 
2D28 
2D2C 
2D30 
2D34 

2D38 
2D3C 
2D40 
2D44 
2D48 



Value 

02002EC0 
FF0043F8 
03000000 
04000000 
05000000 

06000000 
07000000 
08000000 
09000000 
FF000000 



Note that during the IPL only two of 
the CHANQ entries were used (i.e., 
only the first two entries in the 
table have CCB addresses in bytes 
1-3) . For the same system after 
running our worst case workload and 
taking a storage dump, the contents of 
the CHANQ appear as follows: 



— t 



Hex 
Location 

2D24 
2D28 
2D2C 
2D30 
2D34 

2D38 
2D3C 
2D40 
2D44 
2D48 



Value 

01004020 
050040B8 
00002F90 
FF0043F8 
06005898 

04 0036DD 
07000000 
08000000 
09000000 
FF000000 



Note 1 : Only six of the entries were used. 
There were sufficient entries in the table 
to handle the I/O requests with a reserve 
of 4. You would have to decide whether or 
not you should reduce the amount of 
entries. In this case, there are only 16 
extra bytes involved. 
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Note 2 ; In a teleprocessing environment if 
you had 100 channel queue entries and only 
used 50 of them, you would have to do some 
careful evaluation. 



Note 3; If the tenth entry in the table 
had a CCB address, it would indicate the 
possibility that a task or partition may 
have been waiting for a place in the table. 
If this occurs, you should add more entries 
to the table and repeat the procedure until 
the last entry contains no CCB address. 



If the CHANQ value is too large, storage 
space is wasted. If too small, the 
supervisor must wait for an entry in the 
CHANQ table to clear before enqueuing the 
next request. If the CHANQ table entries 
are filled after taking a dump, reassemble 
your supervisor with a larger CHANQ value. 
The following approach gives a more 
efficient way of determining the number of 
CHANQ entries to specify. 



1. Generate your system using the total 
number of logical units (Line Control 
Blocks -LCB- or Channel Control Blocks 
-CCB) as the maximum number of logical 
I/O requests that can be enqueued. It 
is unnecessary for the CHANQ parameter 
value to be larger than the total 
number of system and programmer units. 
The value for the CHANQ parameter may 
be that number or smaller. 



2. Run the programs that use the largest 
number of logical I/O units against 
the system. If your system supports 
multiprogramming, have as many 
partitions running as represent your 
heaviest workload. Use programs that 
use logical double buffering or that 
handle dynamic buffering 
(teleprocessing) . Then use the PDAID 
DUMPGEN program to print a dump that 
formats the CHANQ. 



Determine how many of the channel 
queue entries were used in this worst 
case environment. 



An as aid in determining the number of 
entries used, let us examine the contents 
of the CHANQ. After running our worst case 
workload (the program that is running with 
the most double buffered I/O devices) , and 
using DUMPGEN, the contents of the CHANQ 
might appear as follows: 



r 




1 




CHANNEL 


QUEUE TABLE | 


| DOS 


CHAIN 
PTR 


CCB ADDR CUU | 


| 00 


02 


001CF8 | 


| 01 


FF 


006398 00E | 


| 02 


03 


000000 j 


| 03 


04 


000000 | 


| 04 


05 


000000 | 


| 05 


06 


000000 | 


| 06 


07 


000000 | 


1 07 


08 


000000 j 


| 08 


09 


000000 j 


| 09 


0A 


000000 | 


1 0A 


0B 


000000 | 


| 0B 


OC 


000000 j 


j OC 


0D 


000000 j 


| 0D 


0E 


000000 | 


| 0E 


OF 


000000 | 


I OF 


10 


000000 | 


| 10 


11 


000000 j 


1 H 


12 


000000 | 


1 12 


13 


000000 | 


1 13 


FF 


000000 | 






- _ _ _ _ _ J 



Only two of the entries were used. 
Therefore, we can reduce the amount of 
entries. In this example, the minimum 
CHANQ number, six, can be specified. 



DVCGEN Macro 



CHANNEL RESCHEDULING CONSIDERATIONS 



The type of supervisor generated is an 
important factor in establishing the order 
of DVCGEN statements within each channel 
definition in the PUB table. See Figure 
1.30. Figure 1.14 shows the I/O 
relationship. 

When rescheduling a selector channel, 
the non-MPS supervisor channel scheduler 
always begins at the first device 
definition for the channel within the PUB 
table. Rescheduling a channel is the 
channel scheduler's way of locating the 
next device on the channel that has an 
outstanding I/O request in the CHANQ 
(Figure 1.29). The channel scheduler 
examines the third byte in the PUB table 
entry for a device. If a null pointer (all 
bits on) is found, the scheduler steps to 
the next device within that channel in the 
PUB table. For a non-MPS system, this scan 
always starts at the first PUB entry for 
the channel that has just completed an I/O 
operation. Figure 1.31 lists the device 
type codes. 
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When rescheduling a selector channel in 
an MPS system, the channel scheduler uses a 
rotating scanning technique to ensure that 
each device on a channel gets an equal 
opportunity of being started. The channel 
scheduler in a MPS system retains the 
address of the last PUB entry started for 
each channel. After an I/O interrupt has 
been serviced, the supervisor determines 
that the channel is free, and reschedules 
the channel by going to the last PUB entry 
started for that channel and stepping to 
the next entry. A test determines if that 
device has an outstanding request. If 
there are no outstanding requests for that 
device, the scheduler steps to the next PUB 
entry for that channel. If no requests are 
found, the scheduler steps to the first PUB 
entry for the channel and the scan 
continues until an outstanding request is 
located. If no outstanding requests are 
located, the scan stops after the PUB entry 
for the last device started on that channel 
is checked. 

When rescheduling a multiplexor channel 
with no burst mode devices running, the 
channel scheduler starts another I/O 
operation for this device (if there is 
another request pending in the CHANQ) . If 
burst mode devices are running (BMPX=YES is 
specified in the PIOCS macro) , a rotating 
scanning technique as described for a 
selector channel determines the next I/O 
request to be initiated. 



System Generation Guidelines 



The following rules must be used when using 
DVCGEN macro statements : 



One DVCGEN macro instruction must be 
used for each device on system. For a 
2314/2319, each individual unit needs 
a DVCGEN statement . 



2. The device generated by these macros 
can be changed with ADD and/or DEL 
cards at IPL time. 



3. In a non-MPS supervisor, DVCGEN macros 
must be in ascending channel address 
sequence. SYSRES should be the first 
DVCGEN statement for its channel if it 
is to have the highest priority in a 
non-MPS supervisor. In an MPS 
supervisor, sequence is not important 
since each device on a channel gets an 
equal opportunity at being started. 



4. Switchable units (attached to more 
than one selector channel) are defined 
once on the lowest channel by which 
they are addressable. They may not be 
re-defined as non-switchable units on 
the higher channels. Any switchable 
units must be the last devices 
specified for each channel and must be 
on consecutive channels. 

5. The total number of DVCGEN statements 
must not exceed the total number of 
devices specified in the IODEV 
parameter of the IOTAB macro. 

6. IBM 1052 Printer-Keyboards and IBM 
3210 or 3215 Console Printer-Keyboards 
that are not on-line but were defined 
by DVCGEN statements must be deleted 
by DEL statements when performing IPL 
from the card reader. 
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PUB - TABLE 



PUBTAB 




Channel 



Unit 



Channel Queue Pointer 



TEB& TEBV Pointer or Error Count 



Device Type 



Device Characteristic Code or SAB Pointer 



Channel Scheduler Flags 



Job Control Flags 



= Device busy 

= Switchable device 

= EOJ for SYSRDR or SYSIPT 

= I/O error queued for recovery 

= Operator intervention required 

= Device end posting required 

= Burst device on MPX 

= 7 -track tape unit 



BYTE 7 - 

Bit 0-4: standard MODE assignment for 7 -track tape 
(all ones if not tape, all zeros if device is 
down). 
5: device is assigned to a background job 
6: device is assigned to a foreground 1 job 
7: device is assigned to a foreground 2 job 



BYTE0- Channel number. (Hex 0-7, FF=NULL) BYTE 6 

Bit 
BYTE 1 - I/O device unit number. (HEX 1F= 1052, 
HEX 80 = magnetic tape unit . . .) 

BYTE 2 - HEX 0, 1, 2, . . . points to the first 
channel queue entry for this device. 

BYTE 3 - If device is a magnetic tape unit* and TEBs 
and/or TEBVs are specified, this byte is a 
TEB/TEBV pointer (HEX 1, 2, 3 . . . ) 

If device is a magnetic tape unit* but 
neither TEBs nor TEBVs are specified, 
this byte is an error counter. 

If device is not a magnetic tape unit*, this 
byte is an error counter. 

BYTE 4 - See Figure 1 .31 for device type codes. 

BYTE 5 - SS of the MODE= parameter in the DVCGEN 
macro for tape unit. 

For DASD with seek separation, this byte is 
used as the SAB pointer. With track hold but 
not seek separation supported, this byte con- 
tains a pointer to the Track Hold Table entry 
or X'FF' (with both SKSEP and TRKHLD specified, 
the track hold pointer is found in the SAB entry). 

For MICR type devices, this byte indicates the 
external interrupt line is in use. 

NOTE: A null is generated for each device to be supported by the supervisor. 

Standard physical unit assignments are made to the PUB table at supervisor generation time. PUBs are ordered by 
channel and priority within a channel. 

Bytes 64 and 65 (X'40 1 - '41 ') of the communications region contain the address of the PUB table entry. 
Label PUNTAB identifies the first byte of the table. 
*2400 series or 3420 Magnetic Taf>e units or 2495 Tape Cartridge Reader (TEBs); 2400 series or 3420 Magnetic Tape units only (TEBVs) 



Figure 1.30. Physical Unit Block (PUB) Table 
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Card Code 


Actual Device 


Dev . Type 
X'nn' 


Device Type 


2400T9 


9 -track 2400 Series Magnetic Tape Units 


50 


Magnetic Tape Units 


9 -track 3420 Magnetic Tape Units 


2400T7 


7 -track 2400 Series Magnetic Tape Units 


7-track 3420 Magnetic Tape Units 


2495TC 


2495 Tape Cartridge Reader 


51 


Tape Cartridge Reader 


1442N1 


1442N1 Card Read Punch 


30 


Card Readers - Punches 


2520B1 


2520B1 Card Read Punch 


31 


2501 


2501 Card Reader 


10 


Card Readers 


2540R 


2540 Card Reader 


11 


2540P 


2540 Card Punch 


21 


Card Punches 


2520B2 


2520B2 Card Punch 


20 


1 442N2 


1442N2Card Punch 


22 


2520B3 


2520B3 Card Punch 


20 


1403 


1403 Printer 


40 


Printers 


1403U 


1403 Printer with UCS Feature 


42 


3211 


3211 Printer 


43 


1404 


1404 Printer 


40 


1443 


1443 Printer 


41 


1445 


1445 Printer 


41 


1050A 


1052, 3210, or 3215 Printer -Keyboard 


00 


UNSP 


Unsupported Device 


FF 


Unsupported. No burst mode on multiplexor channel 


UNSPB 


Unsupported Device 


FF 


Unsupported with burst mode on multiplexor channel 


2311 


2311 Disk Storage Drive 


60 


DASD 


2314 


2314 Direct Access Storage Facility 


62 


2319 Disk Storaqe Facility 


2321 


2321 Data Cell Drive 


61 


1412** 


1412 Magnetic Character Reader 


75 


MICR - Magnetic Ink Character Recognition Devices 
and Optical Reader/Sorters 


1419** 


1419 Magnetic Character Reader 


72 


1255 Magnetic Character Reader 


1259 Magnetic Character Reader 


1419P** 


1419 Dual Address Adapter Primary Control 
Unit 


73 


1419S** 


1419 Dual Address Adapter Secondary 
Control Unit 


74 


2701 * 


2701 Data Adapter Unit 


DO 


Teleprocessing lines 

A - SAD0 command when enabling the line 
B = SAD1 command when enabling the line 
C - SAD2 command when enabling the line 
D = SAD3 command when enabling the line 


2702 h 
' D 




Dl 


2703 


2703 Transmission Control 


D2 


2955 


2955 Data Adapter Unit 


D7 


Data link for RETAIN/370 


2671 


2671 Paper Tape Reader 


70 


Paper Tape Reader 


1285 


1285 Optical Reader 


76 


Optical Readers 


1287 


1287 Optical Reader 


77 


1288 


1288 Optical Page Reader 


1017 


1017 Paper Tape Reader with 2826 
Control Unit Model 1 


78 


Paper Tape Reader 


1018 


1018 Paper Tape Punch with 2826 Control 
Unit Model 1 


79 


Paper Tape Punch 


2260 


2260 or 2265 Display Station 


CO 


Display Station 


7770 


7770 Audio Response Unit 


D3 


Audio Response Units 


7772 


7772 Audio Response Unit 


D4 


1017TP 


1017 Paper Tape Reader with 2826 
Control Unit Model 2 


D5 


Paper Tape Reader 


1018TP 


1018 Paper Tape Punch with 2826 Control 
Unit Model 2 


D6 


Paper Tape Punch 


Note: The codes used in the DVCGEN macros are the same codes used in IPL statements. 

* For other teleprocessing devices, see IBM System/360, DOS BTAM and QTAM PLMs, GY30-5001 and GY30-5002. 
** This device type code is also used for the 1270/1275 optical reader/sorters. 



Figure 1.31. Device Type Codes 
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Concepts of Data Management 



This section is written for the reader who 
seeks a general understanding of the 
functions and concepts of data structures 
and storage media. It explains the basic 
concepts of data organization and defines 
some of the terms that will be encountered 
in subsequent sections of this and other 
IBM publications. 

The experienced programmer may find this 
section of interest, but it is written 
primarily for the reader whose experience 
with tape and disk files is limited. 



DATA FILES AND RECORDS 



Data files stored on such media as paper, 
cards, tapes, or disk storage devices, are 
encountered in practically every business 
activity. These files provide the basis 
for most manual, mechanical, and electronic 
data processing. Data files are composed 
of individual records ranging from a few 
records up to thousands or millions of 
records. 

A record can be defined as a collection 
of information comprised of alphameric 
and/or nonalphameric characters related to 
a common identifier. The common identifier 
is known as a record's control field or 
key. Usually one of the prime information 
elements (fields) present within a record 
is used to identify the record. For 
example, man number could be used as the 
key or identifier for a payroll record, and 
policy number could be the key of an 
insurance policy file. 



The size or length of records varies 
from file to file because the size can 
range from a single character up to 
thousands of characters. 



A data field is a sequence of one or 
more characters treated as a processing 
unit of information. A single record 
usually includes one or more logical data 
fields. An individual data field is 
normally identified by its location within 
a record. 

The logical structure of records and of 
fields within records has become 
increasingly important since the advent of 
computers and high-speed recording media 
such as magnetic tapes and disks. This 
logical structure is strongly affected by 
whether a record is fixed or variable 
length . 

Data records of an ASCII tape file may 
include a block prefix and/or padding 
characters. These options are in addition 
to the fields contained in data records 
written in EBCDIC mode. When present, the 
block prefix is the first field of a 
physical record, and it may be 0-99 bytes 
long. DOS can use this field to check the 
length of the physical record only with 
ASCII variable length records. For fixed 
length and undefined records, DOS ignores 
the block prefix on input and does not 
restore this field on output. 

The length of an ASCII physical record 
includes the block prefix field and the 
number of padding characters. Padding 
characters ensure that all blocks conform 
with the required length. DOS accepts 
these padding characters (corresponding to 
EBCDIC X*5F*) on ASCII input but does not 
perform any padding operation on output. 
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Fixed length, unblocked (Figure 2.1) ; Each 
logical record is the same length as the 
physical record. 

For ASCII fixed length, unblocked 
records, the block prefix and padding 
characters are optional. Regardless of the 



presence of these optional fields, ASCII 
fixed length with only one logical record 
per physical record is considered to be 
unblocked. The number of padding 
characters must always be less than the 
size of the logical record. 
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TAPE RECORDS 
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IRG = Inter-Record Gap 

BLPR = Block Prefix (optional) 

PADDING = Padding Characters (optional) 



ASCII TAPE RECORDS 



Physical Record 



Logical Record 



G 



Count 
Area 



G 



Key 
Area 



G 



Data Area 
1 



Count 
Area 



Key 
Area 



■1 



Data Area 
2 



Count 
Area 



Key 
Area 



Data Area 
3 



G 



G - Gap, Area Separator 



DISK RECORDS - WITH KEY AREA 



•* — Physical Record 



Logical Record 



G 



Count 
Area 



:G| 



Data Record 
1 



G 



Count 
Area 



G 



Data Record 
2 



G 



Count 
Area 



G 



Data Record 
3 



Count 
Area 



G 



Data Record 
4 



G - Gap, Area Separator 



DISK RECORDS - WITHOUT KEY AREA 



Figure 2.1. Fixed Length Unblocked Record Format 



< 
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Fixed length, blocked (Figure 2.2) : 
Blocked records are usually considered to 
be two or more logical records within one 
physical record. The number of records in 
each block (blocking factor) is usually 
kept constant. For example, the 
illustrations show blocked records with a 
blocking factor of 3 meaning there are 
three logical records within each block 
(physical record) . 



Each physical record in ASCII fixed 
length, blocked format may contain a block 
prefix and/or padding characters. The 
number of padding characters must be less 
than the size of the logical record. 
Physical records are deblocked until the 
number of bytes remaining in the physical 
record is less than the specified logical 
record length. 



Physical Record 1 



■Physical Record 2 



■Physical Record 3- 



Logical 

Record 

1 



Logical 

Record 

2 



Logical 

Record 

3 



Logical 

Record 

4 



Logical 

Record 

5 



Logical 

Record 

6 



!G! 



Logical 

Record 

7 



Logical 

Record 

8 



Logical 

Record 

9 



Logical 

Record 

10 



Logical 

Record 

11 



IRG = Inter- Record Gap 



TAPE RECORDS 



Physical Record 1 ■ 



■Physical Record 2 ■ 



Log ica I 
Record 
1 



Logical 

Record 

2 



Logical 
Record 
3 



Logical 

Record 

4 



Logical 
Record 
5 



Logical 
Record 
6 



Logical 

Record 

7 



Logical 
Record 



Logical 

Record 

9 



IRG = Inter- Record Gap 

BLPR = Block Prefix (optional) 

PADDING = Padding Characters (optional) 



ASCII TAPE RECORDS 



Physical Record 



H 



Physical Record 2 



G 



Count 
Area 



;gi 



Key 
Area 



!G| 



Logical Record 
Data Area 
1 



Logical Record 
Data Area 
2 



Logical Record 
Data Area 
3 



G 



Count 
Area 



!G! 



Key 
Area 



Logical Record 
Data Area 
4 



Logical Record { 
Data Area 
5 



G = Gap, Area Separator 
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Physical Record 1 



■Physical Record 2- 



■ 



Count 
Area 



!Gi 



Logical Record 
Data Area 
1 



Logical Record 
Data Area 
2 



Logical Record II Count 
Data Area ||g!l Area 

3 



Logical Record 
Data Area 
4 



Logical Record 
Data Area 
5 



Logical Record 
Data Area 
6 



G = Gap, Area Separator 



DISK RECORDS- WITHOUT KEY AREAS 



Figure 2.2. Fixed Length Blocked Record Format 



) 
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Variable length, unblocked (Figure 2.3) ; 
Each physical record contains one logical 
record that can vary in length. Each 
record must contain both a block length 
field (BL) and a record length field (RL) 
giving the size of the block and the size 
of the logical record respectively. The 
first two characters (XX) of the block 
length field (BL) specify the actual block 
length in 16-bit binary form. The last two 
characters (indicated by bb) are binary 
zero. For variable length unblocked 
records, BL specifies the logical record 
length plus 4 bytes (the size of BL) . 

The first four bytes following the block 
length field must contain the record length 
field (RL). The first two bytes (XX) 
specify the length of the logical record 
including the bytes used for RL field 
itself. The remaining two bytes (bb) are 
binary zero. 

For ASCII variable length, unblocked 
records, each physical record may contain a 
block prefix. If the block prefix is four 
bytes long, it may contain the length of 
the physical record that DOS can use for 
checking purposes. Each logical record 
must contain a record length field (dddd) 
giving the size of the logical record in 
unpacked decimal format. If a padding 
character is found in the first position of 
a record length field, all remaining bytes 
in that block are bypassed, and the next 
logical record is retrieved from the next 
block. 



Variable length, blocked (Figure 2.4) : 
or more logical records are contained 
within each physical record. The first 
four bytes (block length field) of each 



One 



physical record (block) specifies the total 
number of bytes in the block. The first 
two bytes (XX) specify the length of the 
block (including the four bytes for the 
block length field itself) . The remaining 
two bytes (bb) are blank. The size of each 
logical record must be placed in a record 
length field (RL) . The RL must be the 
first four bytes of the logical record. 
The first two bytes (XX) of RL specify the 
length of the logical record including the 
bytes used for the RL field. The remaining 
two bytes (bb) are binary zero. 

For ASCII variable length, blocked 
records, each physical record may contain a 
block prefix. For checking purposes, the 
block prefix may contain the length of the 
physical record (in unpacked decimal 
format) if the block prefix is four bytes 
long. The length of each logical record, 
also in unpacked decimal format (dddd) , 
must be placed in the first four bytes of 
the logical record. If a padding character 
is found in the first position of a record 
length field, all remaining bytes in the 
block are bypassed, and the next logical 
record is retrieved from the next block. 

Undefined ; When file records do not 
conform to any of the four previous 
formats, they are classified as undefined. 
For example, any variable length record not 
conforming to IBM's variable length format 
is considered undefined. 

ASCII undefined records may include a 
block prefix and/or padding characters. 
DOS will not attempt to distinguish padding 
characters from the physical record. The 
entire physical record is passed on to the 
user. 



< 
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Physical Record 

•* Logical Record- 



Data 



G 



BL 
xxbb 



RL 
xxbb 



Record 1 



BL 
xxbb 



RL 
xxbb 



Data 



Record 2 



BL 
xxbb 



Data 



RL 
xxbb 



Record 3 



G 



j 3'4 7 

I BL = 84 j RL = 80 



83 1 3j4 7 

'J BL = 104 j RL=100 



103" 3 [4 

I BL = 54 | 



53! 



RL = 50 



, , . > in binary halfword (16 bit) format, plus two blank bytes 

RL = Record Length ) 

IRG = Inter- Record Gap 
G = Gap 

TAPE RECORDS 



Physical Record — 
— Logical Record- 



G 



B 
L 
P 
R 
DDDD 



RL 
dddd 



Data 
Record 1 



B 
L 

P 

R 

DDDD 



RL 

dddd 



Data 
Record 2 



P 








A 




B 




D 


ill 


L 




D 
| 


R 


P 


RL 


N 


G 


R 




G 




DDDD 


dddd 



Data 
Record 3 



IRG = Inter- Record Gap 
BLPR = Block Prefix (optional) 
PADDING = Padding Characters (optional) 

DDDD = length of the physical record if BLPR is 4 bytes long (unpacked decimal) 
dddd = length of logical record in unpacked decimal format 
RL = Record Length 

ASCII TAPE RECORDS 



Physical Record 

■* Logical Record 



Count 
Area 



■ 



BL 
xxbb 



RL 
xxbb 



Data 
Record 1 



■ 



Count 
Area 



!G! 



BL 
xxbb 



RL 
xxbb 



Data 

Record 2 



Count 
Area 



BL 
xxbb 



Data 



RL 
xxbb 



Record 3 



314 7 



83 



BL = 84 



RL-80 



10 314 7 
JBL= 104 | 



103 1 



RL- 100 



BL = Block Length 
RL = Record Le 



• > in binary halfword (16 bit) format, plus two binary zero bytes 



I 314 7 



BL = 54 



RL = 50 



IRG = Inter- Record Gap 
G = Gap 



DISK RECORDS 



Figure 2.3. Variable Length Unblocked Record Format 
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Physical Record 



BL 
xxbb 



Logical Record 



RL 
xxbb 



Data 
Record 1 



RL 
xxbb 



Data 
Record 2 



RL 
xxbb 



Data 
Record 3 



BL 
xxbb 



RL 
xxbb 



Data 
Record 4 



34 



RL=80 



83 84 87 

I RL = 100 



183)184 187 



j BL =234i 
R . _ R , . I > in binary halfword (16 bit) format, plus two blank byt 



RL = 50 



IRG - Inter-record gap 

G = Gap 



TAPE RECORDS 



233 



| 3j4 7 



RL=56 



Physical Record 



Logical Record 



B 
L 
P 
R 
DDDD 



RL 
dddd 



Data 
Record 1 



RL 
dddd 



Data 
Record 2 



RL 
dddd 



Data 
Record 3 



IRG = Inter-Record Gap 

BLPR = Block Prefix (optional) 

PADDING = Padding Characters (optional) 

DDDD = Length of the physical record if BLPR is 4 bytes long (unpacked decimal) 

dddd = Length of logical record in unpacked decimal format 

RL = Record Length 

ASCII TAPE RECORDS 



Physical Record 



■ Logical Record- 



L 

P 

R 

DDDD 



G 



Count 
Area 



M 



Data 



Data 



BL 
xxbb 



RL 
xxbb 



RL 
xxbb 



Data 



RL 
xxbb 



m 



Count 
Area 



G 



BL 
xxbb 



3U 
BL = 234! 



RL=80 



83184 87 
I 
I 



RL = 100 



183 H84 187 
I 



233 ' 



RL=50 



OC f" 9 . I in binary halfword (16 bit) format, plus two binary zero bytes. 
RL — Record Length ) 

IRG = Inter-record gap 
G = Gap 

DISK RECORDS 



Figure 2.4. Variable Length Blocked Record Format 



I 41 



BL = 342 
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BLOCKING RECORDS 



The length of individual data records 
varies with the type of data and the 
application requiring such data. The 
format design of a data record is very 
significant to the efficient use of the 
various storage media available on the 
System/360 and System/ 370. One important 
element in the design of data records 
involves what is commonly called blocking 
and deblocking. Input/output units 
(storage media) are relatively inefficient 
when used to store short blocks of 
information. To increase the efficiency of 
input/output units, data records are 
assembled into blocks of records with size 
convenient and efficient for processing. 
Each physical record on either tape or disk 
requires interrecord gaps. These gaps are 
blank areas that distinguish beginning and 
ending points of a record. If records are 
blocked before loading onto a tape or disk, 
many of these gaps can be eliminated. One 
of the most important advantages of blocked 
records is the increased channel/CPU 
processing time overlap. The average 
number of reads required to locate a record 
can usually be reduced by increasing the 
blocking factor (number of records per 
block) . The greater the blocking factor, 
the greater the chance that the next record 
required will be in the same block. This 
is an important consideration when 
designing jobs that involve file searching 
either on tape or disk. It is particularly 
important when using disk storage 
techniques that develop overflow records. 
Overflow records occur when there are more 
items assigned to a disk track than can be 
stored on that track. 



3420 Magnetic Tape Unit, the IBM 
2311/2314/2319/2321 Direct Access Storage 
Devices (DASD) and the IBM 2540 Card Read 
Punch can be considered physical units when 
data records punched into cards are being 
read into the system. 

A logical file may be of such a size 
that it requires several reels of tape or 
disk packs to contain it. Such a file 
would be referred to as a multivolume file. 
(Each reel of tape, disk pack or each cell 
within the 2321 is considered to be a 
volume.) If a small file does not require 
an entire reel of tape or disk pack to 
contain it, the remaining space on the 
volume could be utilized by another 
complete or partial file. This volume 
would be referred to as a multifile volume. 



DATA MANIPULATION 



Data manipulation with DOS is implemented 
at two distinct levels. The first level, 
physical IOCS requires extensive knowledge 
of System/360 and/or System/370 
input/output devices, as well as a detailed 
understanding of the basic assembler 
language. The second level, logical IOCS, 
uses a series of IBM-supplied macros to 
construct and process data files. Logical 
IOCS requires a minimum knowledge of the 
hardware I/O devices and is easily 
implemented within the problem program by 
the coding of macros. This system is also 
used by most of the DOS high-level 
languages to control I/O operations. 



Blocked records normally require more 
main storage than unblocked records because 
main storage has to contain the block of 
records being read or written on a storage 
device. Also, more main storage is 
required to hold blocking and deblocking 
program instructions. The LIOCS macro 
instructions are designed to handle the 
blocking and deblocking of records so that 
the user need only design the most 
efficient blocking factor for his 
particular data file and equipment 
specifications . 



LOGICAL FILE VS PHYSICAL UNIT 



A logical file consists of one record for 
each item of a group (i.e., an inventory 
file would contain one record for each 
inventory item). A physical unit(s) is 
used to store a logical file. For example, 
the IBM 2400 Magnetic Tape Unit, the IBM 



Physical Input/Output Control System 
(PIOCS) 

Physical IOCS consists of input/output 
(I/O) routines that handle the actual 
transfer of data records between external 
storage devices (cards, tape, disk, etc.) 
and main storage. Program routines 
incorporated in the channel scheduler 
portion of the supervisor handle the 
following functions of PIOCS: 

• Building a schedule of I/O operations 
for all devices on the system (CHANQ 
table) . 

• Starting the actual I/O operations on a 
device (SIO) . 

• Scheduling the start of all I/O 
operations and monitoring all events 
associated with I/O. 
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• Performing error recovery procedures 
(ERP) for all DOS supported devices, 
when necessary. 

A user's problem program normally uses 
logical IOCS for file processing. Logical 
IOCS, in turn, uses physical IOCS to 
perform actual data transfers. There are 
occasions, however, when a user may need to 
bypass the logical IOCS routines to perform 
a particular I/O operation. (Physical IOCS 
is implemented at the assembler language 
level . ) Three macro instructions are 
provided to allow the user to communicate 
directly with physical IOCS. 

CCB This macro instruction creates a 
command control block. This is 
also considered an event control 
block (ECB) . The CCB contains 
the user's information about 
special considerations and/or 
options that he has chosen for 
this I/O operation. It is 
comprised of constant statements 
(DS) that are used in two-way 
communications with the 
supervisor . 

EXCP This macro instruction is 

converted to the proper SVC 
instruction (SVC 0) to request 
execution of a channel program. 
It supplies the location of the 
corresponding CCB to the 
supervisor . 

The EXCP macro instruction 
provides more freedom in 
controlling devices than the 
logical IOCS macros, yet retains 
many of the operational 
advantages of the Disk Operating 
System. DOS provides scheduling 
and queuing of I/O requests, 
efficient use of channels and 
devices, data protection, 
interruption procedures, and 
error recognition and retry. To 
use physical IOCS, however, the 
programmer needs detailed 
knowledge of device control and 
system functions. He must supply 
his own channel programs, using 
the CCW (channel command word) 
assembler instruction statement 
(See Channel Command Word 
section) . 

WAIT This macro instruction tests CCB 
byte 2, bit (traffic bit) to 
determine when an I/O operation 
has been completed. If the 
operation is not completed, the 
supervisor gets control until 
physical IOCS within the 
supervisor sets the traffic bit 
to indicate completion of the 



operation. The WAIT macro should 
always be issued for each 
requested I/O operation. 

Whenever physical IOCS macro 
instructions are used, the programmer must 
construct the channel command words (CCW) 
for his input/output operations. He uses 
the assembler CCW statement to do this. 
See Channel Command Word for detailed 
information on the CCW. Figure 2.5 and the 
following text shows how an I/O operation 
can be traced through physical IOCS. 

A request is made to physical IOCS to 
start an I/O operation by means of the EXCP 
macro instruction in the problem program. 
From information in the CCB, physical IOCS 
determines the channel for which the 
request was made and places the request on 
a queue for that device. If the channel (s) 
or device is not busy, the I/O is started 
and control returns to the problem program. 
If the channel is busy, control returns to 
the problem program, but the I/O request 
waits in the channel queue. When the 
request reaches the top of the channel 
queue, the I/O is started. 

Control returns to the program 
requesting the I/O unless there was an 
error condition detected on the START I/O 
(SIO) instruction. The problem program 
normally continues processing until it 
requires that the requested I/O operation 
be complete (either the information being 
read into main storage is needed or the 
output area must be freed on an output 
operation). At this time, the WAIT macro 
should be issued. The WAIT macro causes 
the now waiting task to be removed from 
task selection until the proper interrupt 
is processed for this device by the 
supervisor. 

Any problem program that is running will 
be interrupted when the I/O operation is 
complete (all data transferred to or from 
main storage and the external device and no 
permanent errors have been detected) . At 
this point, the request is removed from the 
channel queue and normal task selection 
resumes. 

If an error was detected that could not 
be corrected by the device error routines, 
the problem program or the computer 
operator would be notified via a message on 
SYSLOG. User error routines can be 
notified via the CCB to handle conditions 
such as wrong length record. 

Physical IOCS always attempts to perform 
its function so that the time for executing 
an I/O operation is overlapped with the I/O 
operations on other channels and also 
allows the I/O operations to be overlapped 
with processing. 
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I/O DEVICE 
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IREADCCB CCB SYSIPT, RDCCW 



RDCCW CCW 2JNAREA, X'20',80 

INAREA DS CL80 






S> 



Figure 2-5. I/O Operation Using PIOCS 
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Command Control Block (CCB) 



The CCB establishes communication between 
the problem program and physical IOCS. The 
CCB is two doublewords in length with eight 
major fields, as shown in Figure 2.6. The 
optional 8 bytes are generated if the user 
requests that a sense operation be 
performed. on an I/O error. Data 
transferred from the device to main storage 
during a sense operation provides 
information concerning both unusual 
conditions detected in the last operation 
and the status of the device. All data in 
the CCB is in the hexadecimal format. The 
eight fields of the CCB are listed and 
described as follows: 

1. Count Field (Bytes 0.1) : Contains the 
residual count from the channel status 
word (CSW) , that is stored by PIOCS 
when the CCB is removed from the 
queue. The residual count in 
conjunction with the original count 
specified in the last CCW used, 
indicates the number of bytes 
transferred to or from the area 
designated by the CCW. When an input 
operation is terminated, the 
difference between the original count 
in the CCW and the CSW is equal to the 
number of bytes transferred to main 
storage. For an output operation, the 
difference is equal to the number of 
bytes transferred to the I/O device. 

2. Transmission Information (Bytes 2 and 
3) : Used for two-way communication 
between the supervisor and the problem 
program. Each bit within these two 
bytes represents either a condition 
that was detected by the supervisor 
and posted to the user, or a user 
option to be communicated to the 
supervisor. Refer to Figure 2.6. The 
designation pr.pr. indicates those 
bits that the problem programmer may 
set and are not reset by the 
supervisor for each I/O request. 
PIOCS indicates those bits that the 
supervisor is capable of 
setting/resetting just before each I/O 
operation associated with this CCB. 

The user options may be initialized 
at assembly time by specifying the 
third operand of the CCB macro. (See 
Supervisor and I/O Macro listed in the 
Preface for detailed information for 
coding the CCB) . A third operand with 
a value X'0100' instructs PIOCS to 
return to the user after each I/O 
operation for this CCB whether or not 
any errors have occurred. It is then 
up to the user to handle all aspects 
of error recovery and/ or retry, even 
to the point of determining if an 



error does exist. The only additional 
information that the supervisor 
provides under this circumstance is 
the CSW status information posted in 
bytes 4 and 5 of the user CCB. If the 
user specifies the fourth operand 
(Sense Address) , the sense information 
is present in the sense area that the 
user has specified (if an error 
condition existed at the end of the 
I/O operation) . 



Note : Bytes 2 through 5 are ANDed off 
(mask setting is X*1F050000*) by PIOCS 
when the CCB is placed in the queue. 
Communication bits that were set on by 
the problem program are left on 
because an AND instruction is used by 
PIOCS for resetting bytes 2 through 5. 

3. CSW Status Bits (Bytes 4,5) : Contains 
the CSW status information that is 
stored by PIOCS before control returns 
to the problem program. 

Note : The particular bits that are 
turned on in bytes 2 through 5 
indicate the conditions that were 
detected by PIOCS and/or the problem 
program by the specification of the 
third operand of the CCB macro. 

4. Symbolic Unit Number (Bytes 6,7) : 
Contains the 2-byte hexadecimal 
representation of SYSnnn (symbolic 
unit) . This value represents the 
location of the logical unit in the 
LUB table (see Figure 1.19) and is 
placed in the CCB by the problem 
programmer's specification of the 
symbolic unit to be used for this I/O 
operation. The symbolic unit is 
converted to a 2-byte hexadecimal 
representation by the CCB macro. The 
first byte indicates the class of the 
symbolic unit (system class=X*00 , , 
programmer class=X ' 01 • ) . The second 
byte of the representation indicates 
the number of the unit within one of 
the previously mentioned classes. An 
example of such a conversion can be 
illustrated with the symbolic unit 
SYS007, which converts to X'OIO?'. 

5. Byte 8 : Contains the length of the 
block prefix. This length is 
X'OO'-X'eS* for ASCII input tapes and 
X'OO* or X'O**' for ASCII output tapes. 
For EBCDIC tape files, this byte is 
always X'OO" . 

6. CCW Address (Bytes 9-11) : Contains 
the address of the CCW that is 
associated with this CCB. This 
address is placed in the CCB by the 
specification of the second operand of 
the CCB macro. In the case of chained 
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CCWs, this operand specifies the 
address of the first CCW. 

Byte 12 : Contains information used by 
physical IOCS that must not be 
modified by the user. 

CCW Address in CSW (Bytes 13-15) ; 
Contains the CCW address from the CSW 
stored by PIOCS before control returns 
to the problem program. A CCB that 
has been queued by PIOCS to service a 
problem program I/O request cannot be 
used for a second problem program I/O 
request until the first request has 
been completed. 

Optional Sense CCW (Bytes 16-23) : 
Bytes 16-23 are appended to the CCB by 
the CCB macro expansion when the user 
wants sense information on 



unrecoverable I/O errors returned. If 
the user specifies a sense address by 
coding the fourth operand of the CCB # 
an 8-byte CCW for reading sense 
information is generated as the last 
field of the CCB. The name field 
(sense address) of the area that the 
user supplies must have an assigned 
length attribute of at least one byte. 
Physical IOCS uses this length 
attribute in the CCW to determine the 
number of bytes of sense information 
the user wants at this sense address. 
For more detailed information 
concerning this sense information see 
the Principles of Operation listed in 
the Preface . For detailed information 
regarding the actual coding of the 
physical IOCS macros refer to 
Supervisor and I/O Macros listed in 
the Preface. 
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Bytes 

Used for- 



Transmission 
Information 



CSW Status Bits 
4 5 



Symbolic Unit 
Address 

6 7 



Reserved for 
Logical IOCS 



CCW Address 
9 11 



Reserved for 
Physical IOCS 
12 



CCW Address 
in CSW 
13 15 



Optional 
Sense CCW 



16 



Residual Count 



Transmition 
Information 
Between Physical 
IOCS and 
Problem Program 



1 (Note 1) 


~~ ~~ — _ 1 


1 Byte 4 


Byte 5 ~~ — — _ ' 


j BIT DESIGNATION 


BIT DESIGNATION ! 


1 32 Attention 


40 Program - controlled , 


| 33 Status modifier 


interruption . 


1 34 Control unit end 


41 Incorrect length | 


1 35 Busy 


42 Program check i 


| 36 Channel end 


43 Protection check 1 


| 37 Device end 


44 Channel data check ' 


| 38 Unit check 


45 Channel control check ' 


39 Unit exception 


46 Interface control check . 


k„ 


47 Chaining check j 






"""--- ^ ! 




~"~ ~~ ^ i 



Hexadecimal 
Representation 
**1 of SYSnnn 

SYSRDR =0000 

SYSIPT =0001 

SYSPCH =0002 

SYSLST = 0003 

SYSLOG = 0004 

SYSLNK =0005 

SYSRES 

SYSSLB 

SYSRLB 

SYSUSE 

SYSREC 

SYSCLB 

SYS00O 

SYS001 

SYS221 



= 0006 
= 0007 
= 0008 
= 0009 
= 000A 
= 000B 
= 0100 
= 0101 
= 0IDD 



Buffer Offset: 
ASCII Input Tapes 
X'OO'-XW 

ASCII Output 
Tapes Fixed: 
X'00' 

Variable: X'00'or 
X'04' 

Undefined: X'00 1 



Address of CCW 
Associated with 
this CCB 



X'80'-CCB being 
used by ERP 

X'40'-Channel 
Appendage 
Routine Present 
for Teleprocessing 
Device 

X'20'- Sense 

Information 

Desired 

X' 10'- Message 
Writer 

X'08'-EU Tape 
Error 

X'02'-Tape ERP 
Read Opposite 
Recovery 

X'Ol'-Seek 
Separation or 
Console Buffering | 



Address of CCW 
in the CSW 
Stored at 
Channel End, 
or Address of 
the Channel 
Appendage 
Routine for 
Teleprocessing 
Devices 



- 23 -i 



8 Bytes 
Appended to the 
CCB when Sense 
Information is 
Desired 



Byte 2 

















Return Tape Read 






Traffic Bit 
(Wait) 


End -of -File 
( /* or /&) 

3211- 

UCSB Parity 
Check (Line 
Complete) 


Unrecoverable 
I/O Error 


Accept 

Unrecoverable 

I/O 


Return DASD 
Data Checks 
2671 errors, or 
1017/1018 
errors to the 
user 


Post at 
Device End 


Data Check, 1018 
Data Check, 2540 
or 2520 Equipment 
Check, DASD 
Data Checks on 
Read or Verify 
Command, or 3211 


User Error 
Routine 




(Note 5) 


(Note 2) 








(Note 5) 


Passbook Requested 
(Notes 3 & 6) 









1 


2 


3 


4 


5 


6 


7 




On By-*- 


PIOCS 


PIOCS 


PIOCS 


Pr.Pr. 


Pr. Pr. 


Pr. Pr. 


Pr.Pr. 


Pr.Pr. | 











Byte 


3 










DASD- 


DASD- 


DASD- 


2540, 2520- 


Non -Recovery 


No -Record - 


Carriage 


Command 




Data Check in 


Track Overrun 


End of Cylinder 


Equipment Check 


Questionable 


Found Condition 


Channel 9 


Chaining 




Count Area 


MICR- 


MICR- 


Tape- 


Condition: 


(Retry on 2311, 


Overflow or 


Retry from 




MICR- 


Intervention 


(Note 4) 


Read Data Check 


Card- 


2314, or 2319) 


Verify Error 


the next CCW 




SCU Not 


Required 


1287/1288- 


DASD- 


Unusual 




for DASD 


to be executed 




Operational 


1285/1287- 


Hopper Empty 


Any Data Check 


Command 










1285/1287/1288 


Keyboard 


in Document 


1285/1287 


Sequence 




1287 Document 






Data Check 


Correction in 


Mode 


Equipment Check 


DASD- 




Mode - Late 






3211- 


Journal Tape 


3211- 


1017/1018 


No Record Found 




Stacker Select 






Print Check/ 


Mode 


Line Position 


Data Check 


1285/1287/1288- 










Equipment Check 


1017- 


Error 


3211- 


Document Jam 




1288 -End of 








Broken Tape 


(Note 7) 


Print Check/ 


or Torn Tape 




Page 








3211- 




Data Check 


3211- 












Print Quality/ 






UCSB Parity Check 












Equipment Check 






(Command Retry) 








p.. 





1 


2 


3 


4 


5 


6 


7 




Set On By-»- 


PIOCS 


PIOCS 


PIOCS 


PIOCS 


PIOCS 


Pr. Pr. 


PIOCS 


Pr. Pr. | 



PIOCS = Physical IOCS 

Pr. Pr. = Problem Program 
Note 1 . Bytes 4 and 5 contain the status bytes of the Channel Status Word (Bits 32 -47). If byte 2, bit 5 is on and device end results as a separate interrupt, device end will be ORed into CCB byte 4. 
Note 2 . Indicates /* or /& statement encountered on SYSRDR or SYSIPT . Byte 4, bit 7 (unit exception) is also on . 
Note 3. DASD data checks on count not returned. 

Note 4. For 1255/1259/1270/1275/1412/1419, disengage. For 1275/1419D, I/O Error in external interrupt routine (channel data check or busout check). 
Note 5. The traffic bit (Byte 2, bit 0) is normally set on at channel end to signify that the I/O was completed. If byte 2, bit 5 has been set on, the traffic bit and bits 2 and 6 in byte 3 will be set on 

at device end . Also see Note 1 . 
Note 6. 1018 ERP does not support the Error Correction Function. 
Note 7. This error occurs as an equipment check, data check, or FCB parity check. 



Byte 



Bit 



Condition Indicated 



1 (ON) 



(OFF) 



On Values 
for Third 
Operand in 
CCB Macro 



Mask for 
Test Under 
Mask 
Instruction 



Traffic Bit (WAIT). 



I/O Completed. Normally set 
at Channel End. Set at Device 
End if bit 5 is ON . 



I/O requested and not 
completed . 



X'80' 



1 End of File on System Input. 



3211 UCSB Parity Check (line complete) 



/* or /& on SYSRDR or SYSIPT . 
Byte 4, Unit Exception Bit is 
also ON. 
Yes 



X'40' 



No 



2 Unrecoverable I/O Error 



I/O error passed back due to 
program option or operator 
option . 



No program or operator 
option error was passed 
back. 



X'20' 



3 Accept Unrecoverable I/O Error 
(Bit 2 is ON) 



Return to user after physical 
IOCS attempts to correct I/O 
error . 2 



Operator Option: 
Dependent on the Error 



X'1000' 



XMO 1 



2671 data check . 

1017/1018 data checks. 
Return any DASD data checks. 



Operator Options: 
Ignore, Retry, or Cancel. 
Ignore or Cancel . 
Return to user . 



Operator Option: 
Retry or Cancel . 
Cancel . 



X'0800' 



X'08" 



5 Post at Device End. 



Device End condition is posted; 
that is, byte 2, bit and byte 
3, bits 2 and 6 set at Device 
End . Also byte 4, bit 5 is set . 



Device End conditions are 
not posted. Traffic bit is 
set at Channel End. 



X'0400' 



X'04 1 



Return: Uncorrectable tape read data 
check (2400 -series, 3420, or 2495); 1018 
data check; 2540 or 2520 punch equip 
ment check; DASD read or verify data 
check; 321 1 passback requested . 
(Data checks on count not returned.) 



Return to user after physical 
IOCS attempts to correct 3211, 
tape, or DASD error. Return 
to user when 1018 data check. 1 * 



Operator Option: 
Ignore or Cancel for taprs, 
punches, or paper tape 
punch (1018). Retry or 
cancel for DASD. 



X'0200 1 



X'02' 



7 User Error Routine 



User handles error recovery. 3 



A physical IOCS error 
routine is used unless the 
CCB sense address operand 
is specified. The latter re- 
quires user error recovery. 



X'0100' 



X'01' 



Data check in DASD count Field. 

Data check - 1285, 1287, or 1288. 

MICR -SCU not operational . 

3211 Print Check (equipment check). 



Yes -Byte 3, bit 3 is OFF; 

Byte 2, bit 2 is ON. 

Yes 

Yes 

Yes 



No 

No 
No 
No 



X'80' 



DASD Track overrun . 

1 01 7 broken tape . 

Keyboard correction 1285 or 1287 in 

Journal Tape Mode. 

3211 print quality error (equipment 

check). 

MICR intervention required. 



Yes 
Yes 
Yes 

Yes 

Yes 



No 
No 
No 

No 

No 



X'40' 



End of DASD Cylinder. 
Hopper Empty 1287/1288 Document 
Mode. 

MICR - 1 255/1 259/1 270/1 275/1 41 2/ 
1419, disengage. 
- 1275/1 41 9D, I/O error in 
external interrupt routine . 
3211 line position error . 5 



Yes 
Yes 

Document feeding stopped , 

Channel data check or 

Busout check . 

Yes 



No 
No 



No 



No 



X'20' 



Figure 2.6. Command Control Block (CCB) (Part 2 of 3) 
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Byte 


Bit 


Condition Indicated 


On Values 
for Third 
Operand in 
CCB Macro 


Mask for 
Test Under 
Mask 
Instruction 


l (ON) 


(OFF) 


3 


3 Tape read data check (2400 -series or 
2495); 2540 or 2520 punch equipment 
check; or any DASD data check. 
1017/1018 data check. 
1285, 1287, or 1288 equipment check . 
321 1 data check (print check). 


Operation was unsuccessful . 

Byte 2, bit 2 is also ON . 

Byte 3, bit is OFF. 

Yes 

Yes 

Yes 


No 

No 
No 
No 




X'10' 


4 Questionable Condition . 

Nonrecovery 

UCSB parity check (command retry) . 


Card: Unusual command 

sequence (2540) . DASD: 

No record found . 

1 285/1287/1288: Document 

jam or torn tape . 

Yes 


No 




X'08' 


5 1 No record found condition 


Retry command if no record 
found condition occurs (disk). 


Set the questionable 
condition bit ON and 
return to user . 


X'0004' 


X'04' 


6 Verify error for DASD or Carriage 
Channel 9 overflow 

1287 document mode - late stacker 
select . 

1288 End -of -Page (EOP). 


Yes. (Set ON when Channel 9 
is reached only if Byte 2, bit 5 
is ON). 
Yes 

Yes 


No 

No 
No 




X'02' 


7 Command Chain Retry 


Retry begins at last CCW 
executed . 


Retry begins at first CCW 
of channel program . 


X'OOOT 


X'Ol' 



1 User Option Bits. Set in CCB macro. Physical IOCS sets the other bits OFF at EXCP time and ON when the condition specified occurs. 

2 I/O program check, command reject, or tape equipment check always terminates the program. 

3 For System/360, the user must handle all error or exceptional conditions except Channel Control Check, Interface Control Check, 
I/O Program Check, and I/O Protection Check. For System/370, the user may handle Channel Control Checks and Interface Control 
Checks. The occurrence of a channel data check, unit check, or chaining check causes a byte 2, bit X'20' of the CCB to turn on, 
and completion posting and dequeuing to occur. I/O program and protection checks always cause program termination. Incorrect 
length and unit exception are treated as normal conditions (posted with completion). Also, the user must request device end posting 
(CCB byte 2, bit X'04') in order to obtain errors after channel end. 

** Error correction feature for 1018 is not supported by physical IOCS. When a 1018 data check occurs and CCB byte 2, bit X'02' is on, 

control returns directly to the user with CCB byte 3, bit X'lO' turned on. 
s A line position error can occur as a result of an equipment check, data check, or FCB parity check. 

Figure 2.6. Command Control Block (CCB) (Part 3 of 3) 



Channel Command Word (CCW) 



To aid the programmer in using physical 
IOCS, an assembler instruction statement, 
CCW (channel command word) , is provided. 
This CCW assembler instruction statement is 
a convenient means to define and generate 
the 8-byte channel command words needed for 
the channel program. See Figure 2.7 for 
the format of the CCW assembler 
instruction. 

r t t ■ 1 

| Name | Operation | Operand | 

(. + + -I 

| Any | CCW | Four operands separated | 
| Symbolj I by commas specifying thej 
jor Not j j command code, data ad- j 
| Used | j dress, flags, and count. j 
l j. . x -___J 

Figure 2.7. Format of the CCW 



Command Code 

The CCW command code (1 byte) may be 
expressed as a decimal number, hexadecimal 
representation, or as a symbol that has 
been equated to the proper hexadecimal or 
decimal value (e.g., 19, X'O', PR, where 
PR EQU 19 respectively) . The assembler 
moves, or converts and moves, the command 
code to the first byte of the machine 
language CCW it is generating. Each I/O 
device has a specific set of commands to 
which it will respond; any other commands 
to that device are rejected. 



Data Address 

This field must contain a data address 
unless the CCW command is a control command 
(for example, skip to channel 1 for a 
printer) . Normally this field is expressed 
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as a symbol for ease of program relocation 
and reflects the address of the 
input/output area. 



Flags 

The third field of the CCW mnemonic is used 
to communicate special considerations to 
the channel regarding this CCW. The value 
of the flag byte may be expressed as a 
decimal number, hexadecimal character or as 
a symbol that has been equated to the 
proper decimal or hexadecimal value. 
Although it is referred to as the flag 
byte, only the five high order bits (bits 
32-36 of the resultant CCW) represent 
individual flags. The three low order bits 
must be zero in their final hexadecimal 
form. The function of each flag bit is as 
follows : 

Bit 32 (High Order Bit of the Flag Field) ; 
This is the chain data (CD) flag. Chaining 
refers to a series of CCWs in contiguous 
(consecutive) doubleword storage locations 
that are linked to each other forming a 
chain. 



Bit 33 : Bit position 33 of the CCW is the 
command chaining (CO flag. This bit when 
set to one causes the next sequential CCW 
to initiate another operation on the same 
I/O device. 

For example, it is possible to read two 
cards into main storage as a result of one 
EXCP macro instruction. Two CCWs with the 
CC flag set in the first CCW are required. 

CCW1 CCW 2, DATA, X* 40*, 80 

CCW 2,DATA+80,X , 00 , ,80 

In this example, CCW1 initiates a read 
command. The first card is read into 
storage locations DATA through DATA+79. 

Because the CC flag bit in the first CCW 
is set to one, the second CCW is used to 
initiate another card read operation. The 
next card is read into storage locations 
DATA+80 through DATA+159. 

Note that when data chaining, only one 
I/O operation occurs. The data from the 
one I/O record is placed in main storage 
under control of two or more CCWs. 



Data chaining permits the reading or 
writing of an I/O record from different 
areas of main storage. 

If the CD flag bit is set to 1 (CD flag 
on) , the data address and count in the next 
sequential CCW are also used in storing a 
data record. Both CCWs pertain to the same 
I/O record. 

When data chaining, the command bytes of 
successive CCWs are ignored (unless it is a 
transfer in channel (TIC) ) , but the field 
must contain a valid command. Only the 
first CCW"s command byte is used. It is 
important to note that data chaining 
pertains to only one I/O operation or data 
record. This could be one punch card or 
one tape record or one line of print and so 
forth. 

Example ; To read columns 1-30 of a punch 
card into storage beginning at location ONE 
and columns 31-80 into storage beginning at 
location TWO, two CCWs could be used. The 
first CCW would have its CD flag bit set to 
1 as shown: 

CCW1 CCW 2,ONE,X , 80 i ,30 
CCW 2, TWO, X* 00* ,50 

CCW1 causes thirty bytes to be read into 
storage starting at location ONE. The 
second CCW causes the next fifty bytes of 
the card to be read into storage starting 
at location TWO. 

Note : The ability to data chain is 
dependent upon device and channel speeds. 



When command chaining, each CCW controls 
a different I/O operation. The commands 
that are chained do not need to be the 
same. For instance, it is possible using 
one EXCP macro instruction to do a 
write-backspace-read combination with a 
magnetic tape unit by command chaining with 
three CCWs in one EXCP macro instruction. 

When command chaining, an I/O interrupt 
cannot occur at the end of each command, 
but can occur when the last command is 
executed. 

When command chaining, each command 
processes one physical record. If the byte 
count of the record does not agree with the 
count field of the CCW, an incorrect length 
indication results. 

Bit 34 : Bit position 34 of the CCW is the 
suppress incorrect length indication (SLI) 
flag. The SLI bit may be turned on to 
prevent an indication to channel of an 
unequal compare between the byte count 
specified in the CCW and the actual bytes 
read from the record. 

Example of Incorrect Length : If you want 
to read columns 1-50 of a card into main 
storage starting at location BUFFER and 
bypass the remaining 30 columns, the 
following CCW can be used: 

CCW1 CCW 2, BUFFER, X* 20', 50 

An incorrect length indication results 
because one CCW causes the device to 
process one complete record and the device 



» &©o : %v 
9 c o o -- KtO 
00'° • v'J 



Section 2: Data Management 107 



could not be stopped on the 51st byte. 
When an incorrect length indication occurs, 
the status bit in the CCB is set for 
testing by the programmer. 

If the SLI flag bit is on, it suppresses 
the incorrect length indication for each 
data record. For example, if you want to 
read columns 1-40 of a card into main 
storage starting at location BUFFER1 and 
columns 41-6 into main storage starting at 
location BUFFER2, the following two CCWs 
could be used: 

CCW1 CCW 2,BUFFER1,X , 80 , ,40 
CCW2 CCW 0,BUFFER2,X , 20 , ,20 

CCW1 causes 40 bytes to be read into main 
storage starting at location BUFFER1. CCW2 
causes the next 20 bytes of the card to be 
read into storage starting at location 
BUFFER2. A breakdown of the flag bytes 
would be: 

CCW1 Data Chaining 

CCW2 Suppress incorrect length indication 

Note that the SLI flag is not required for 
the first CCW. The incorrect length 
indication is relevant to an entire data 
record and not to a given CCW. The SLI 
flag is present in the second CCW because 
it is the last CCW for the record and the 
total value of the two CCW count fields 
does not equal the actual record length. 

Bit 35 : Bit position 35 of the CCW is the 
SKIP flag. The SKIP flag suppresses the 
transfer of information into main storage. 
It can be used together with the data 
chaining feature to read selected portions 
of an I/O record into main storage. To do 
this, the CD flag is used along with bit 35 
of the CCW. For example, if columns 51-80 
of a punch card are to be read into 
locations DATA through DATA+29, the card 
reader reads all 80 columns of information 
and attempts to transfer 80 bytes of data 
into main storage. The channel needs 2 
CCWs. 

CCW1 CCW 2,DATA,X , 90*,50 
CCW 2, DATA, X* 00', 30 

CCW1 has both the CD and the SKIP flag bits 
on. 

Because the skip flag bit is on, CCW1 is 
used to suppress the transfer of data into 



main storage. The count field causes 50 
bytes to be bypassed. 

Because the CD flag bit is on, the 
second CCW is fetched after the first 50 
bytes have been skipped. The second CCW 
causes bytes 51 through 80 to be read into 
storage starting at location DATA. 



Bit 36 : Bit position 36 of the CCW is the 
program control interrupt (PCI) flag. CPU 
normally receives an I/O interrupt at the 
end of the I/O operation. However, bit 
position 36 of the CCW can be used to 
signal an I/O interrupt before the end of 
the operation. 

When a CCW is fetched that has its PCI 
flag bit on, CPU receives an I/O interrupt 
as soon as it can accept it. In this way, 
CPU is notified of the progress of an I/O 
operation. This notification could be used 
to initiate the processing of the data 
records that have been read into main 
storage by the preceding CCWs in the chain. 

I/O interrupts normally occur at the end 
of the operation. An interrupt caused by 
PCI would not affect the I/O operation. 
The interrupt is taken by the CPU and the 
I/O operation continues in the same manner 
as if the interrupt had not occurred. 

The PCI-caused interrupt occurs as soon 
as possible after start of execution of the 
command containing the PCI flag. The 
occurrence of the interrupt may be delayed, 
depending on the model of System/360 and/or 
the particular device that it is operating. 

A more detailed explanation of the CCW 
flags can be found in Principles of 
Operation listed in the front of this 
manual . 



Count 

The count field gives the total number of 
bytes in the storage area (the physical 
size of the records being read or written) . 
The count field specifies any number of 
bytes up to 65,535. Except for a CCW 
specifying a transfer in channel, the count 
field cannot contain the value zero. 

To illustrate the use of physical IOCS, 
Figures 2.8 and 2.9 show a sample program 
with a related flowchart. 
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DISKREAD 



Lood base 
register 
Load R3 with 
record count 



READ VOL 



Read fhe 
volume label 



CCB 

VOLREAD 



Move VTOC 
address from 
volume label 
to seek 



PRTVOL 



Print the 
volume label 


CCB 

VOLPRT 


READ VTOC | 




Read o record 
From VTOC 


CCB 
VTOC READ 


PRTVTOC 1 




Print o record 
from VTOC 


CCB 
VTOCPRT 



Update the SEEK 
field to read the 
next VTOC record 



NO 



Read 
six records 
in VTOC 



YES 



EOJ 



Figure 2.8. Flowchart for EXCP Coding Example 
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PAGE 1 


LOC 


OBJECT CODE A0DR1 


ADDR2 


STMT 


SOURCE 


STATEMENT FDOS CL3-5 


10/31/69 


000000 






1 

2 


DISKREAO 


START 
PRINT 



NOGEN 


0010 


000000 






3 




BALR 


h,0 


0030 


000002 


0540 




4 




USING 


*,<t 


0020 


000002 


4130 0006 


00006 


5 




•U 


3,6 










6 


READVOL 


EXCP 


VOLREAO READ THE VOLUME LABEL 


00005 








10 




WAIT 


VOLREAD WAIT FOR THE READ TO COMPLETE 




OOooiA 


D204 4002 410B 00002 


0010B 


16 




MVC SEEK+2<5),V0LUME+11 SET UP SEEK/SEARCH ARGUMENT 










17 


PRTVOL 


EXCP 


VOLPRT PRINT THE VOLUME LABEL 


0070 








21 




WAIT 


VOLPRT WAIT FOR PRINT TO COMPLETE 


0080 








27 READVTOC 


EXCP 


VTOCREAD READ THE VTOC 


0090 








31 




WAIT 


VTOCREAO WAIT FOR THE READ TO COMPLETE 


0100 








37 


PRTVTOC 


EXCP 


VTOCPRT PRINT A VTOC RECORD , KEY AND DATA 


0110 








41 




WAIT 


VTOCPRT WAIT FOR PRINT TO COMPLETE 


0120 


00005C 


4360 4006 


0O0D6 


47 




IC 


6,SEEK+6 UPDATE THE RECORD COUNT IN THE 




000060 


4166 0001 


00001 


48 




LA 


6,1(6) SEEK/SEARCH ARGUMENT 


0140 


000064 


4260 4006 


00006 


49 




STC 


6.SEEK+6 STORE UPDATED ID INTO SEEK/SEARCH ARG. 




0000 68 


4630 4034 


00034 


50 




BCT 


3.REA0VTOC 










51 


EOJ 


EOJ 




0180 


00006F 


0700 




54 




CNOP 


0,4 










55 


VOLREAO 


CCB 


SYS004, VOLCCW 


0190 








66 


VTOCREAO 


CCB 


SYS004, VTOCCCW 










77 


VOLPRT 


CCB 


SYS006, VOLPTCCW 


0210 








88 


VTOCPRT 


CCB 


SYS006, VTOCPCCW 


0220 


OOOOBO 


0700000040000006 




99 


VOLCCW 


CCW 


LONGSEEK, SEEK, CC, 6 SEEK TO CYLINDER 0, HEAD 




000088 


2900000760000004 




100 


SEARCHKY 


CCW 


SRCHKEYE, KEYSCH ,CC+SLI ,4 SEARCH KEY EQUAL <V0L1» 




OOOOCO 


080000B800000000 




101 




CCW 


TIC, SEARCHKY, 0,0 TIC BACK TO SEARCH 




0O0OC8 


0600010020000050 




102 




CCW 


READDATA, VOLUME, SLI .L'VOLUME READVOL LABEL DATA FIELD 




OOOODO 


00000000000000 




103 


SEEK 


DC 


X'OOOOOOOOOOOOOO' 


0270 


000007 


E5D6D3F1 




104 


KEYSCH 


DC 


CL4'V0L1* 




000008 


0000000000 














OOOOFO 


070000D0 40000006 




105 


VTOCCCW 


CCW 


LONGSEEK, SEEK, CC, 6 SEEK TO THE VTOC CYLINDER/HEAD 




0O0OE8 


3100000260000005 




106 


SEARCHID 


CCW 


SRCHIDE, SEEK+2.CC+SLI ,5 SEARCH ID EQUAL FOR VTOC RCD 




OOOOFO 


080000E800000000 




107 




CCW 


TIC, SEARCHID, 0,0 TIC BACK TO SEARCH 




0O0OF8 


OE0001002000008C 




108 




CCW 


REAOKOTA, VTOCRCD, SLI, L' VTOCRCD READ KEY/DATA FROM VTOC 




000100 






109 


VTOCRCD 


DS 


0CL140 


0330 


000100 






110 


VOLUME 


OS 


0CL80 


0340 


000100 






111 


KEY 


DS 


CL44 


0350 


00012C 






112 


DATA 


DS 


CL96 


0360 


10018C 


E5D6D3E404C54003 




113 


VOLHEAD 


DC 


C'VOLUME LABEL' 


0370 


000198 


E5E3D6C340D2C5E8 




114 


KEYHEAD 


DC 


C'VTOC KEY' 


0380 


0001 AO 


E5E3D6C340C4C1E3 




115 


OATAHEAD 


DC 


C'VTOC DATA' 


0390 








116 


* ******************************************************************** 










117 


* PRINT 


VOLUME HEADER ANO SPACE ONE 










118 


* PRINT 


VOLUME LABEL AND SPACE THREE 










119 


* ******************************************************************** 




"001 &9 


00000000000000 














000180 


0900018C6000000C 




120 


VOLPTCCW 


CCW 


PR INTSP1,V0LHE AD, CC+SLI,L« VOLHEAD 




0001B8 


•l°00010020O0O050 




121 




CCW 


PRINTSP3, VOLUME, SLI, L'VOLUME 










122 


* ******************************************************************** 




. — 






123 


* PRINT 


VTOC 


KEY HEADING 


■ ■ 














PAGE 2 


LOC 


OBJECT CODE ADDR1 


ADDR2 


STMT 
124 


SOURCE 
* PRINT 


STATEMENT FDOS CL3-5 
KEY OF VTOC RECORD 


10/31/69 








125 


* PRINT 


DATA 


HEADING 










126 


* PRINT 


DATA 


PORTION OF VTOC RECORD 










127 


* ******************************************************************** 




0001CO 


0900019860000008 




128 


VTOCPCCW 


CCW 


PRINTSP1.KEYHE AD, CC+SLI.L' KEYHEAD 




0001C8 


190001006000002C 




129 




CCW 


PRINTSP3,KEY,CC+SLI,L'KEY 




000100 


09000 1A0 60000009 




130 




CCW 


PRINTSP1,DATAHEAD,CC+SLI,L'DATAHEAD 




0001O8 


1900012C20000060 




131 




CCW 


PRINTSP3, DATA, SLI, L'DATA 










132 


* ******************************************************************** 










133 


* SAMPLE DASD 


CHANNEL COMMAND EQUATES 










134 


* ******************************************************************** 




000007 






135 


LONGSEEK 


EQU 


07 




000029 






136 


SRCHKEYE 


EQU 


41 




00^008 






137 


TIC 


EQU 


08 




000006 






138 


READDATA 


EOU 


06 




oooo-u 






139 


SRCHIDE 


EOU 


49 




0O000F 






140 


READKDTA 


EQU 


14 










141 


* ******************************************************************** 










142 


* SAMPLE 1403 


OR 1443 PRINTER COMMAND EQUATES 










143 


* ******************************************************************** 




000009 






144 


PRINTSP1 


EOU 


09 




OOOOto 






145 


PRINTSP3 


EOU 


25 










146 


* ******************************************************************** 










147 


* FLAG OPERANDS 










148 


* ** ADD 


SYMBOLS TOGETHER FOR COMBINATIONS SUCH AS CD+SL I************* 










149 


* ******************************************************************** 




000080 






150 


CO 


EQU 


128 CHAIN DATA 




000040 






151 


CC 


EQU 


64 COMMAND CHAIN 




000020 






152 


SLI 


EQU 


32 SUPPRESS LENGTH INDICATION 




000010 






153 


SKIP 


EOU 


16 SKIP PORTIONS OF THE RECORD 




000008 






154 


PCI 


EOU 


8 PROGRAM CONTROLLED INTERRUPT 




000000 






155 
156 


ENDCCWS 


EQU 
END 


END OF CCW LIST 


0460 


0001FO 


00000070 




157 






=A( VOLREAD) 




0001F4 


00000090 




158 






=A( VOLPRT) 




0CC1F8 


00000080 




159 






=A( VTOCREAO) 




nnn-j c r 


00^000 AC 




160 






=A( VTOCPRT) 





















Figure 2.9. Physical IOCS Sample Program 
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Logical Input/Output Control System 

(LIOCS) 

Logical IOCS (LIOCS) provides data 
management, functions required to locate and 
access logical records in a file (just as 
the problem programmer would) . LIOCS uses 
physical IOCS to accomplish actual data 
transfer and device control. The data 
management functions include: 



• Organization (blocking and deblocking) 
of logical records. 

• Control (switching) of I/O areas when 
more than one area is used. 

• Handling of the open and close 
requirements, and end-of-file and 
end-of -volume conditions . 

• Resolving symbolic references to 
physical I/O devices. 

• Translating data in the I/O areas from 
ASCII to EBCDIC (on input) and from 
EBCDIC to ASCII (on output) . 

With IBM-supplied macro instructions, 
logical IOCS eliminates the repetitive 
detail coding required for standardized 
input and output routines. These logical 
IOCS macros, referred to as imperative 
macros, supply the facilities for reading, 
writing, blocking and deblocking records, 
file labeling, and error checking. To make 
use of these facilities, logical IOCS 
imposes certain requirements that must be 
handled by the problem programmer. These 
include descriptive entries in other 
IBM-supplied macros, called declarative 
macros, to specify the characteristics of a 
file that is to be processed by logical 
IOCS. The IBM assembler program uses the 
descriptive information when processing the 
macro statements to tailor the logical IOCS 
routines for the specific application. 

Logical IOCS handles data transferred to 
or from I/O devices as logical files of 
data. When logical IOCS determines that an 
I/O area contains no logical record (or 
records, in the case of blocked records) 
needing processing, it issues a physical 
IOCS macro to execute the actual data 
transfer. Figure 2.10 shows the 
relationship between logical and physical 
IOCS for a logical IOCS imperative GET 
macro issued to an input file when one I/O 
area is used. 

Logical IOCS is a generative system that 
uses the capabilities of a macro language. 
It is this generative nature that provides 
the problem programmer with the ability to 
include only those routines needed for a 
specific job or job step. 



LOGICAL IOCS PROCESSING METHODS 



The IBM Disk Operating System provides 
logical IOCS routines to process records in 
sequential order, in random order by the 
Direct Access Method (DAM) , or randomly and 
sequentially by the Indexed Sequential File 
Management System (ISFMS). Sequential 
processing applies to all files on serial 
I/O devices (such as card reader, tape, 
printer, etc) , and to records on IBM 2311, 
2314, and 2319 disk or 2321 data cell 
devices when they are processed serially. 
The types of processing performed by DAM 
and ISFMS apply only to files of Direct 
Access Storage Device (DASD) records. 

Logical disk files can be data set 
secured. A data-secured file cannot be 
accessed accidentally by problem programs. 
The data set security function provides a 
record on the system log each time a 
data-secured file is opened. It is the 
user's responsibility to insure data 
security. 

In addition, logical disk files can have 
the track hold option. When track hold is 
specified in the DTF, a track that is being 
modified by a task in one partition cannot 
be concurrently accessed by a task or 
subtask in the same or another partition 
provided that all programs competing for a 
track specify the track hold option. Any 
program that does not use the track hold 
option will not be denied access to a 
track, and can modify a track that is being 
held by another program. Therefore, all 
programs accessing the same file should 
have the track hold option. 



Sequential Processing 



Sequential processing reads, writes and 
processes successive records in a logical 
file. For example, card records are 
processed in the order the cards are fed. 
Tape records are processed starting with 
the first record after a header label and 
continuing through the records to the 
trailer label. DASD records are processed 
starting with a beginning DASD address and 
continuing in order through the records on 
successive tracks and cylinders to the 
ending address. 

A sequential file on DASD is contained 
within one or more sets of limits called 
extents that are specified by the user in 
job control EXTENT/XTENT statements or 
commands. If the logical file consists of 
more than one set of limits, logical IOCS 
automatically processes each set as 
required by the user. The records within 
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Problem Program Partition 



Problem 
Program 



Issue GET- 



Next 

instruction 
after GET 
macro 
expansion 



Logical IOCS 



■♦-Provide record 
(deblock) and 
return to the 
Problem Program/ 



If I/O required, 
issue EXCP macro. 

and 



WAIT macro 



Return to the 
Problem Program 
when I/O is 
complete, or, if an 



ASCII input file, 
translate data to 
EBCDIC in I/O area 
and return to 
problem program. 



Supervisor 



Physical IOCS 

(Channel 

Scheduler) 



■♦-Determine channel 
and: 

a) If channel is not 
■♦-busy, start I/O — 



b) If channel is busy, 
place in channel 
queue and return 
to LIOCS. 



f 



When I/O is complete, 
return to LIOCS via 
Interrupt Routine. 



I/O 
Device 



♦- Start Device 



I/O Complete 



Figure 2.10. Retrieving a Record Using Logical IOCS 



each set must be adjacent and contained 
within one volume (disk pack or data cell) . 
The sets are not required to be adjacent or 
on the same volume. Sequential processing 
of a DASD file written by the Direct Access 
Method can be performed if the physical 
structure of a sequential file is present. 



record key, if records contain key areas, 
or the record identifier (ID) that is in 
the count area of each DASD record. 
Logical IOCS seeks the specified track and 
searches for the record on that track, or 
on the succeeding tracks in the cylinder. 



Direct Access Method (DAM) 



Indexed Sequential File Management System 
(ISFMS) 



The Direct Access Method (DAM) processes 
records contained on IBM 2311, 2314, 2319, 
or 2321 DASD devices that are usually 
organized in a random manner. 

Logical IOCS locates a DASD record for 
processing by referring to a record 
location reference supplied by the problem 
program. The location reference consists 
of two parts: a track reference and a 
record reference. The track reference 
specifies the track (or the first of 
multiple tracks) to be searched for the 
record. The record reference may be the 



DASD records contained within an indexed 
sequential file can be processed in a 
random order or in sequential order by 
control information. Both orders use the 
control information of the records (such as 
employee number, part number, etc) , that is 
available in the key area of each DASD 
record. Any record stored at any location 
in the logical file can be processed by the 
random method. The user supplies ISFMS 
with the key (control information) of the 
desired record. ISFMS searches for the 
record and makes it available for 
processing. 
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In sequential processing, ISFMS makes a 
series of records available. The records 
are available one after the other in order 
by the control information (key) in the 
records. The user specifies the first 
record to be processed. ISFMS retrieves 
the succeeding records (on demand) from the 
logical file, in key order, until the 
problem program terminates the operation. 

ISFMS creates an organized file and then 
adds to, reads from, and updates records in 
that file. The file is organized from 
records that are presorted by control 
information. As the DASD records are 
loaded, ISFMS constructs indexes for the 
logical files. The indexes permit 
individual records to be found in 
subsequent processing operations. The 
indexes are created in such a way that 
records can be retrieved randomly or 
sequentially. If records are added to the 
file at a later date, ISFMS updates the 
indexes to reflect the new records. 



MAIN STORAGE REQUIREMENTS 



Logical IOCS routines are generated as part 
of the problem program. Imperative macro 
expansions, that serve as linkages to the 
logical or physical IOCS routines, are 
generated in-line at the point the macro is 
used in the problem program. The open, 
close, EOF/EOV, and other special purpose 
routines are called into the B-transient 
(logical transient) area as required. The 
physical IOCS routines used by logical IOCS 
are generated as part of the supervisor 
program. 



MODULAR/TABULAR SYSTEM 



The terms modular and tabular mean that the 
system uses tables in conjunction with data 
handling modules to implement its 
functions. 

The modular/tabular system has the 
following advantages: 

• Saves assembly time by allowing the 
data handling modules to be generated 
separately and stored in the 
relocatable library for subsequent use. 

• Uses one module for many files if the 
device types are the same and the files 
are similar. 

The major advantage is the ability to use 
one logical IOCS module with many different 
files. It not only saves a large portion 



of main storage but also makes the system 
more versatile. 



The modular/tabular combination for a 
specific file is generated by two macros: 
the file definition macro in the form 
DTFxx, and the module generation macro in 
the form xxMOD. 

The file definition macros describe the 
logical file, indicate the type of 
processing to be used for the file, and 
specify main storage areas (work area, I/O 
area, etc.) for the file. A number of 
file definition macros define the files 
processed by logical IOCS, and one defines 
files processed by physical IOCS (DTFPH). 
The file to be processed determines the 
type of file definition macro to use. 

The module generation macros generate 
the data handling logic modules. These 
modules contain generalized routines needed 
to perform the functions of the logical 
IOCS imperative macros. The generalized 
routines in the logic modules are altered 
and made more specific through various 
parameters (specified by the problem 
programmer) included in the xxMOD macro 
statements. It is possible, therefore, to 
generate many variations of a particular 
type of logic module, each specifically 
suited to the need of the problem 
programmer. 



DTF (Define the File) Macros 



Whenever logical IOCS imperative macro 
instructions are used in a problem program 
to control the transfer of records in a 
file, that file must be defined by a 
declarative DTF macro instruction. The DTF 
macro instruction describes (through 
various parameters specified by the problem 
programmer) the characteristics of the 
logical file, indicates the type of 
processing for the file, and specifies the 
main storage areas and routines. Detailed 
descriptions of the logical IOCS file 
definition (DTF) macros and their 
parameters appear in Supervisor and I/O 
Macros listed in the Preface . 

In general, the IBM-supplied file 
definition (DTF) macros are device 
oriented. In addition, three macros, 
DTFSR, DTFBG and DTFEN are supported by the 
Disk Operating System to provide upward 
compatibility from the IBM System/360 Basic 
Operating System (8K system). A brief 
description follows for each of the DTF 
macros available to users of the IBM Disk 
Operating System. 
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DTFCD ; Define The File for a Card Device. 
To define a file associated with the 
records on a card unit. 



DTFCN : Define The File for a CoNsole. To 
define a file associated with the console 
I (1052, 3210, 3215) printer. 

DTFDA ; Define The File for Direct Access 
| method. To define a file when DASD (Direct 
Access Storage Device) records are to be 
processed by the Direct Access Method. 

DTFDI ; Define The File for Device 
Independent system files. To define files 
assigned to the device independent system 
logical units SYSRDR, SYSIPT, SYSPCH, and 
SYSLST. 

DTFIS : Define The File for Indexed 
Sequential file management system. To 
define a file organized and processed by 
the indexed sequential file management 
system. 

DTFMR ; Define The File for Magnetic 
Recognition. To define a file associated 
with a magnetic ink character recognition 
(MICR) device. 

DTFMT ; Define The File for Magnetic Tape. 
To define a file associated with a magnetic 
tape device. 

DTFOR : Define The File for an Optical 
Reader. To define a file associated with 
an optical character reader device. 

DTFPH: Define The File for processing by 
PHysical IOCS. To define a magnetic tape 
or DASD file with standard labels that is 
to be processed by physical IOCS when the 
OPEN and CLOSE macros are used for label 
processing. DTFPH parameters define the 
magnetic tape and DASD files. No other 
files processed by physical IOCS require 
definition. 

Only the following logical IOCS 
functions can be performed for files 
defined by a DTFPH macro: 

• Check the header labels on input files, 
and close these files when requested. 

• For ASCII tape files only: 
Translate labels to EBCDIC for input 
files and check them. Create labels 
and translate them to ASCII for output 
files. 

• Create header labels on output files, 
and create trailer labels when the file 
is closed. 

• Force end-of-volume on an output file 
when requested. 



when a DTFPH macro instruction is 
encountered at assembly time, the assembler 
builds a DTF table that includes only the 
parameters needed for the OPEN, CLOSE (R), 
FEOV, and FEOVD routines. The OPEN, 
CLOSE (R), FEOV, and FEOVD macro expansions 
call the open and close routines into the 
supervisor B-transient area at object time. 

DTFPR : Define The File for a PRinter. To 
define a file associated with a printer 
device. 

DTFPT : Define The File for Paper Tape. To 
define a file associated with a paper tape 
device . 

DTFSD : Define The File for Sequential 
DASD. To define sequential files on a 
direct access storage device (DASD) . 

DTFSR : Define The File in a SeRial type 
file device. To define a file for 
sequential processing of records on any 
IOCS supported I/O device. 

The DOS DTFSR macro definition accepts 
either the BOS or BPS DTFSR macro as valid 
input. After determining the device type 
required, the DOS DTFSR macro calls the 
appropriate DOS DTF macro from the source 
statement library. The DTF macro called by 
the DOS DTFSR then sets up a DTF table in 
the usual manner. 

The DOS DTFSR macro definition only 
allows upward compatibility and should not 
be used as a statement in the user's DOS 
source deck. 

DTFBG : Define The File for 
BeGin-definition. Must be punched with 
DTFBG in the operation field and DISK in 
the operand field. The name field is left 
blank. DTFBG is included in DOS to provide 
compatibility with the BOS DTFSR macro 
instruction. 



DTFEN: 



Define The Field ENd. To show 



there are no more DTF source statements to 
process. The DOS DTFEN macro definition 
allows upward compatibility for BOS and BPS 
users. 



MOD (Module Generation) Macros 



Each DTF (except DTFCN, DTFPH and DTFSR) is 
linked to a logical IOCS module generated 
by an xxMOD macro instruction. These 
modules provide the necessary instructions 
to perform the input/output functions 
required by the problem program. For 
example, the module can read or write data, 
test for unusual input/output conditions, 
block or deblock records, or place logical 
records in a work area. 
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Some of the module functions are 
provided on a selective basis, according to 
the parameters specified in the xxMOD macro 
instruction. The problem programmer has 
the option of selecting (or omitting) some 
of these functions according to the 
requirements of his program. Omitting some 
of these functions results in smaller main 
storage requirements for a particular 
module . 

There are two options for MOD macros. 
The user can: 

1. Insert the MOD macro instruction with 
its file parameters in the problem 
program source deck. In this case, 
the logic module is assembled in-line 
with the problem program. 

2. Choose at system generation time to 
generate the logic modules needed for 
his file formats and system 
configuration. To do this, source 
decks using macro parameters to 
describe the file attributes are 
punched for each MOD macro statement. 
The logic module macro definition 
generates its own unique name, or the 
user can name the module in the name 
field of the MOD macro statement. The 
user name overrides the name the macro 
definition normally generates. 

For each type of xxMOD macro, the problem 
programmer can generate many logic modules 
by issuing the macro with varying 
parameters for each required module. The 



logic modules can be cataloged in the 
relocatable library. The CATALR control 
cards are automatically generated when the 
module is assembled. 



At assembly time, the assembler produces 
an EXTRN (External Symbol) card for every 
V-type constant (or EXTRN statement) , in 
the user program. The assembler expansion 
of the DTF statement produces an EXTRN card 
with the name of the logic module needed to 
support the parameters that were specified 
in the DTF macro. The IBM-generated module 
names indicate the type of file and the 
support that each is capable of supplying 
for the DTF. Refer to Figure 2.11 for a 
breakdown of these names. Because of the 
descriptive nature of the IBM standard 
names, the programmer should be careful 
when specifying his own names for the logic 
modules or overriding the IBM standard 
names. At the time this program is 
link-edited, the linkage editor resolves 
these EXTRN symbols (AUTOLINK). If the 
program is not to be executed immediately, 
the linkage editor catalogs the program 
into the core image library. 

Figure 2.12 gives the module name 
prefixes used in the IBM-supplied programs. 
Figure 2.13 shows the relationship of the 
DTFxx and the xxMOD macros. The DTFCN 
macro is unique in that it generates its 
own logic module and combines it with the 
DTF table. The logic module for DTFCN is 
always punched in the object deck, along 
with the DTF table (A of Figure 2.13). 
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Logic 
Module 


Prefix 


4th 
Character 


5th 
Character 


6th 
Character 


7th 
Character 


8th 
Character 


Subsetting/ 
Supersetting 
+ Permitted 
* Not Permitted 


CDMOD 


IJC 


F RECFORM=FIXUNB 
V RECFORM=VARUNB 
U RECFORM=UNDEF 


A CTLCHR=ASA 
Y CTLCHR=YES 
C CONTROL=YES 
Z Neither CTLCHR nor 
CONTROL specified 


B RDONLY=YES and 

TYPEFLE=CMBND 

C TYPEFLE=CMBND 

H RDONLY=YES and 

TYPEFLEHNPUT 
1 TYPEFLE=INPUT 
N RDONLY=YES and 
TYPEFLEOUTPUT 
O TYPEFLEOUTPUT 


Z Neither WORKA nor 

IOAREA2 specified 
W WORKA=YES 
1 IOAREA2=YES 
B Both WORKA=YES and 

IOAREA2=YES 
Z WORKA=^ES not 

specified (CMBND 

file only) 


DEVICE=2540 

1 DEVICE=1442 

2 DEVICE=2520 

3 DEVICE=2501 

4 DEVICE=2540 and 
CRDERR=RETRY 

5 DEVICE=2520 and 
CRDERR=RETRY 


IJC FAB BO 

VYCI 1 

U + HW2 

CIZ3 

ZN 4 

O 5 


PRMOD 


IJD 


F RECFORM=FIXUNB 
V RECFORM=VARUNB 
U RECFORM=UNDEF 


A CTLCHR=ASA 

Y CTLCHR=YES 

C CONTROL=YES 

S STLIST=YES 

Z Neither CTLCHR nor 
CONTROL nor 
STLIST specified 


C = B if ERROPT=YES 

(ERROPT=name in 

DTFPR) and 

PRINTOV=YES 
= P if PRINTOV=YES 

and ERROPT is not 

specified (ERROPT= 

RETRY or is omitted 

in DTFPR) 
= E if ERROPT=YES 

(ERROPT=name in 

DTFPR) 
= Z if neither ERROPT 

(ERROPT=RETRY or 

is omitted in 

DTFPR) nor 

PRINTOV is 

specified 


1 IOAREA2=YES 

Z IOAREA2 not specified 


V RDONLY=YESand 
WORKA=YES 

W WORKA=YES 

Y RDONLY=YES 

Z Neither RDONLY nor 
WORKA specified 


* * + * * 

IJD FAB 1 V 

VYEZ W 

US + Y 

+ P Z 

C Z 

z 


PTMOD 


UE 


S SCAN=YES 

Z SCAN not specified 


T TRANS=YES and 

SCAN not specified 
Z TRANS not specified 


F RECFORM=FIXUNB 
and SCAN=YES 

U RECFORM=UNDEF 
and SCAN=YES 

Z SCAN not specified 
and/or DEVICES 01 8 


1 DEVICE=1017 

2 DEVICE=1018 

Z DEVICE=267I or not 
specified 


Z 


UE ZZZZZ 
Z TZZ 
S ZF Z 
S ZU Z 
Z Z Z 1 
Z T Z 1 
S ZF 1 
S ZU 1 
S Z Z 2 
ZT Z2 


MTMOD 

(GET/ 

PUT) 


IJF 


F RECFORM=FIXUNB 

or FIXBLK 
N RECFORM=UNDEF 

(ASCII files) 
V RECFORM=VARUNB 

or VARBLK (EBCDIC 

mode) 
U RECFORM=UNDEF 

(EBCDIC mode) 
X RECFORM=FIXUNB or 

FIXBLK (ASCII files) 
R RECFORM=VARUNB or 

VARBLK (ASCII mode) 
S RECFORM=SPNUNB 

or SPNBLK (spanned 

records) 


B READ=BACK 
Z READ=FORWARD or 
not specified 


C CKPTREC=YES 
Z CKPTRECnot 
specified 


W WORKA=YES 

Z WORKA not specified 


M ERREXT=YES and 

RDONLY=YES 
N ERREXT=YES 
Y RDONLY =YES 
Z Neither ERREXT nor 
RDONLY specified 


* + + + + 
IJF F B C WM 
NZ Z ZY 
R + 
U N 
X Z 
+ 
S 
V 


MTMOD 

(Work 

Files) 


UE 


W TYPEFLE^VORK 


E ERROPT=YES 

Z ERROPT not specified 


N NOTEPNT=YES 
S NOTEPNT=POINTS 
Z NOTEPNT not 
specified 


Z 


M ERREXT=YES and 

RDONLY=YES 
N ERREXT=YES 
Y RDONLY=YES 
Z Neither ERREXT nor 

RDONLY specified 


+ + + 

IJF WE N Z M 

Z S Y 

Z + 

N 

Z 



Figure 2.11. Generated Name Structure for Logic Modules (Part 1 of 2) 
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Logic 
Module 


Prefix 


4th 
Character 


5th 
Character 


6th 
Character 


7tb 
Character 


8th 
Character 


Subsetting/ 
Supersetting 
+ Permitted 
* Not Permitted 


SDMOD 

(GET/ 

PUT) 


IJG 


C SDMODFx specifies 

HOLD=YES 
F SDMODFx does not 

specify HOLD=YES 
R SDMODUx specifies 

HOLD=YES 
U SDMODUx does not 

specify HOLD=YES 
P SDMODVx specifies 

HOLD=YES (spanned 

records) 
Q SDMODVx does not 

specify HOLD=YES 

(spanned records) 
S SDMODVx specifies 

HOLD=YES 
V SDMODVx does not 

specify HOLD=YES 


U SDMODxU 
1 SDMODxl 
O SDMODxO 


C ERROPT =YES and 

ERREXT=YES 
E ERROPT =YES 
Z Neither ERROPT nor 

ERREXT specified 


M TRUNCS=YES and 

FEOVD=YES 
T TRUNCS=YES 
W FEOVD=YES 
Z Neither TRUNCS nor 

FEOVD specified 


B CONTROL=YES and 

RDONLY^ES 
C CONTROL=YES 
Y RDONLY=YES 
Z Neither RDONLY nor 

CONTROL specified 


+ * + * + 
IJG C UCT B 
F 1 E ZY 
+ OZ + 
R C 
U Z 
+ 
P 
Q 
V 
+ 
P 
S 
V 


SDMOD 

(Work 

Files) 


IJG 


T HOLD=YES 
W HOLD=YES not 
specified 


C ERROPT=YES and 

ERREXT=YES 
E ERROPT=YES 
Z Neither ERROPT nor 

ERREXT specified 


N NOTEPNT=YES 
R NOTEPNT=fOINTRW 
Z NOTEPNT not 
specified 


C CONTROL=YES 
Z CONTROL not 
specified 


T RDONLY=YES and 

UPDATE=YES 
U UPDATE=YES 
Y RDONLY=YES 
Z Neither RDONLY nor 

UPDATE specified 


+ + + + + 

IJG T C NCT 

WE R ZY 

Z Z + 

U 

Z 


ISMOD 


IJH 


A RECFORM=BOTH and 

!OROUT=ADD or 

ADDRTR 
B RECFORM=FIXBLK 

and IOROUT =ADD 

or ADDRTR 
U RECFORM=FIXUNB 

and IOROUT=ADD or 

ADDRTR 
Z RECFORM not 

specified (IOROUT 

specifies LOAD or 

RETRVE) 


A IOROUT=ADDRTR 
1 IOROUT=ADD 
L IOROUT=LOAD 
R IOROUT=RETRVE 


B TYPEFLE=RANSEQ 
G IOAREA2=YES and 
TYPEFLE=SEQNTL or 
IOROUT=LOAD 
R TYPEFLE=RANDOM 
S TYPEFLE=SEQNTL 
Z Neither TYPEFLE nor 
IOAREA2 specified 
(IOROUT =ADD or 
LOAD) 


B CORINDX=YES and 

HOLD=YES 
C DORINDX=YES 
O HOLD=YES 
Z Neither CORINDX 

nor HOLD is specified 


F CORDATA=YES, 
ERREXT =YES and 
RDONLY=YES 
G CORDATA=YES and 

ERREXT=YES 
O CORDATA=YES and 

RDONLY=YES 
P CORDATA=YES 
S ERREXT =YES and 

RDONLY=YES 
T ERREXT=YES 
Y RDONLY=YES 
Z Neither CORDATA 
nor RDONLY nor 
ERREXT specified 


+ + + + + 

IJH A A B B F 

B 1 ROO 

z + + + + 

+ A B C S 

AR S ZY 

U * + + 

Z L G G 

S P 

+ + 

G T 

Z Z 


DAMOD 


IJI 


F RECFORM=FIXUNB 
B RECFORM=UNDEF 

(handles both UNDEF 

and F1XUNB) 
S RECFORM=SPNUNB 
V RECFORM=VARUNB 


A AFTER=YES 

Z AFTER not specified 


1 IDLOC=YES 
E IDLOC=YES and 

FEOVD=YES 
R FEOVD=YES 
Z Neither FEOVD nor 

IDLOC specified 


H ERREXT=YES and 

RELTRK=YES 
P ERREXT=YES 
R RELTRK=YES 
Z Neither ERREXT nor 

RELTRK specified 


W HOLD=YES and 
RDONLY=YES 
X HOLD=YES 
Y RDONLY=YES 
Z Neither HOLD nor 
RDONLY specified 


+ + + + + 

IJI B AE HW 

F Z 1 P X 

+ Z Z Z 

s + + + 

V E H W 

R R Y 

ZZZ 


DIMOD 


IJJ 


F Fixed unblocked 
record format 


C ASA and System/360 
control character 
support for printers 
and punches 


B TYPEFLEOUTPUT 
1 TYPEFLE=INPUT 


1 IOAREA2=YES 

Z IOAREA2 not specified 


C RDONLY^ES 
D RDONLY not 
specified 


+ + * . 
IJJ F C B 1 C 
1 Z D 


ORMOD 


IJM 


F RECFORM=FIXUNB 
X RECFORM=FIXBLK 
U RECFORM=UNDEF 
D RECFORMMJNDEF 
and BLKFAC=YES 


C CONTROL=YES 
Z CONTROL not 
specified 


1 IOAREA2=YES 

W WORKA=YES 

B IOAREA2=YES and 

WORKA=YES 
Z Neither IOAREA2 nor 

WORKA specified 


T Device is in tape mode 
D Device is in document 
mode 


Z 


* + * * 
IJM DC B D Z 
F Z 1 T 
U W 
X Z 


MRMOD 


IJU 


S Single address adapter 
D Dual address adapter 


Z 


Z 


Z 


Z 


IJU D Z Z Z Z 
S 



Figure 2.11. Generated Name Structure for Logic Modules (Part 2 of 2) 



Section 2: Data Management 117 







. J J I 

1 < „ > xxxxxx 




IHD 


S/360 COBOL processing subroutines 




MB 


System Service and System Control 




fuc 


Card logic 




IJD 


Printer logic 




IJE 


Paper tape logic 


DATA , 


1 UF 


Magnetic tape logic 


MANAGEMENT 


\ IJG 


Sequential DASD logic 




IJH 


Indexed Sequential DASD logic 




' Ml 


Direct Access DASD logic 




VMJ 


Device independent logic 




MK 


PL/I processing subroutines 


DATA 


ML 


Teleprocessing routines 


MANAGEMENT - 


-MM 


Optical Reader logic 




MN 


Audio Response Vocabulary File Utility 




MO 


Disk Sort/Merge 




MP 


Tape Sort/Merge 




MQ 


D-level Assembler 




MR 


RPG compiler 




MS 


S/360 COBOL compiler 


DATA 


MT 


Basic FORTRAN, and FORTRAN subroutines 


MANAGEMENT - 


-MU 


Magnetic Readers logic 




MV 


Autotest 




IJW 


Utilities 




MX 


PL/I compiler 




MY 


F-level Assembler 




MZ 


OLTEP 




IKL 


COBOL LCP 




ILA 


ANS COBOL compiler 




ILB 


ANS COBOL processing subroutines 




ILC 


CE Serviceability Programs 




ILF 


F-level FORTRAN IV and FORTRAN IV subroutines 




ILH 


Tape and Disk Sort/Merge 



Interrelationships of the DTF and Module 
Macro Instructions 



The DTFCD, DTFDA, DTFDI, DTFIS, DTFMR, 
DTFMT, DTFOR, DTFPR, DTFPT, and DTFSD 
declarative macros are similar in that they 
each generate a DTF table that references 
an IOCS logic module (refer to B of Figure 
2.13). The first 20 bytes of each table 
have the same format, that is, a command 
control block (CCB) and a logic module 
address. The remainder of each table is 
tailored to the particular device and file 
type. 

The description that follows is general 
and includes all of the DTF types included 
in B of Figure 2.13. 



| Figure 2.12, 



DOS Relocatable Library 
Module Name Prefixes 



Reentrant Modules 



A reentrant module is a logic module that 
can be used asynchronously, or shared by 
more than one file. The RDONLY=YES 
parameter in the module generation macro 
generates a reentrant logic module. The 
RDONLY (read only) parameter implies that 
the generated logic module is never 
modified in any way regardless of the 
processing requirements of any file (s) 
using the module. To provide this feature, 
unique save areas external to the logic 
module are established, one for each task 
using the module. Each save area must be 
72 bytes and doubleword aligned. Before a 
logic module is entered or an imperative 
macro is issued to the file, the task must 
provide the address of its unique save area 
in register 13. 



Reentrant modules include: CDMOD, 
DAMOD, DIMOD, ISMOD, MTMOD, and SDMOD. 



DTFCN 




DTFCD 




CDMOD 






DTFDA 


DAMOD 




DTFDI 


DIMOD 


DTF Table and 
Logic Module 


DTFIS 


ISMOD 




HI 




DTFMR 


MRMOD 




DTFMT 


MTMOD 




DTFOR 


ORMOD 




DTFPR 


PRMOD 




DTFPT 


PTMOD 




DTFSD 


SDMOD 
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DTFPH 




DTF Tables 
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Logic Modules 
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Partial 
DTF Table 




DTFEN 






DTFSR 
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Relationsh 


8K BOS 
Compatibility 




Figure 2.13. 


Hi 

du 
ip. 


s 


i ^ 


lac 


:ro 





118 DOS System Programmer's Guide 



When one of these DTF macro instructions 
is encountered at assembly time, the 
assembler builds a DTF table tailored to 
the DTF parameters. The table contains: 

• Device CCB (Figure 2.6). 

• A V-type statement used by the Linkage 
Editor to resolve the linkage to the 
logic module associated with this DTF. 

• Logic indicators, that is, one I/O 
area, two I/O areas, device type, etc. 

• Addresses of all of the areas and 
controls used by this device (except 
work files) . 

Regardless of the method of assembling 
logic modules and DTF tables (with the main 
program or separately) , a symbolic linkage 
results between the DTF table and the logic 
module. The Linkage Editor resolves these 
linkages at edit time. 

To accomplish the linkage between the 
DTF table and the logic module, the 
assembler generates a V-type address 
constant in the DTF of a named CSECT in the 
logic module. To resolve this linkage, the 
linkage symbols (module names) must be 
identical. 

Figure 2. 11 shows the relationship of 
the program, the DTF and the logic module. 
It also shows a DTFDA macro with a filename 
of DISK. The assumed parameters have 
generated a request for a DAMOD named 
IJIFZIZZ. Based on this name, the linkage 
editor was able to locate the module. The 
read statement generated coding to load the 
address of the DTF table into register 1. 
This gives the program access to the DAMOD 
address, and the program branches to the 
required routine within the module. 



DISK 


DTFDA 

DC V(IJIFZIZZ) 






^DAMOD 


— 


MJIFZIZZ 


CSECT 

READ DISK, KEY 






*L 1,=A(DISK) 


Get DTF table address. 




*L 15,16(1) 


Get logic module address 
located 16 bytes from 
start of DTF table. 




*BAL 14,24(15) 


Branch to read routine in 
logic module . 


* Macro g 


enerated coding 





Figure 2.14. 



Coding Example of DTF and 
Module Relationship 



generates an in-line expansion that links 
the instruction to the DTF table (thus the 
logic module) for the specified file. For 
an operand, the imperative macro 
instruction must always contain the 
filename in the DTFxx macro describing the 
file. 



IMPERATIVE MACROS 



The problem programmer issues imperative 
logical IOCS macro instructions to initiate 
such functions as opening a file, making 
records available for processing, writing 
records that have been processed, 
controlling physical device operations, 
etc. 

For each imperative macro issued by the 
problem programmer, the assembler program 



Figure 2.15 summarizes the macro 
instructions provided by IBM for logical 
IOCS. Figure 2.16 further defines the 
general function of each of the macro 
instructions and indicates the devices with 
which they are used. The Supervisor and 
I/O Macros listed in the Preface gives a 
detailed explanation of each of the 
imperative macros. 
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MACROS 


DTFCD 


DTFCN 


DTFDA 


DTFDI 


DTFIS 


DTFMR 


DTFMT 


DTFOR 


DTFPH 


DTFPR 


DTFPT 


DTFSD 


DTFSR 


CHECK 












X 


X 










X 




CLOSE(R) 


X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


CNTRL 


X 




X 








X 
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X 




X 


X 


DISEN 












X 
















DSPLY 
















X 












ENDFL 










X 


















ERET 






X 








X 










X 




EXETL 










X 


















FEOV 














X 










X 


X 


FREE 






X 


















X 1 




GET 


X 


X 




X 


X 


X 


X 


X 






X 


X 


X 
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X 
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X 


X 
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NOTE 














X 










X 




OPEN(R) 


X 




X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


X 


POINTR 
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X1 




POINTS 
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X 1 
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PRTOV 
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X 


PUT 


X 
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X 
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X 


X 


X 


X 
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X 


X 
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X 


X 


RESCN 
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SETFL 
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TRUNC 














X 










X 


X 


WAITF 






X 




X 


X 




X 












WRITE 






X 




X 




X 










X 




1 . Work files only. 



Figure 2.15. Logical IOCS Imperative Macros and DTFs 
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Notes: 1 . Applies only if DTFSR, DTFMT, DTFDA, or DTFPH LABADDR or XTNTXIT is specified. 

2. In the 2520 or 2540, GET normally reads cards in the read feed. If TYPEFLE =CMBND is specified, GET reads cards at the 
punch - feed -read station . 

3. PUT rewrites on input DASD record if UPDATE is specified. 

4. In the 1442, 2520, or 2540, PUT punches an input card with additional information if TYPEFLE =CMBND is specified. 

5. Applies only to blocked input records. 
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Figure 2.16. Logical IOCS Imperative Macros and Devices 
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SEQUENTIAL FILE ORGANIZATION 



Line Printers 



Card Files 



The DTFCD/CDMOD macros provide the user 
with the ability to read (GET) a record 
from a card reader or punch (POT) a record 
on a card punch (up to 80 characters in 
both cases) . The user has the option of 
specifying one or two I/O areas (IOAREA1 
and IOAREA2) , also called buffer areas, to 
hold the data transferred to main storage 
from the device, or vice versa. The second 
buffer area allows the user to overlap 
processing while the following record is 
read or the previous record is punched. 
The user can process the data read (or data 
to be punched) in the buffer area if only 
one area is specified. If two buffer areas 
are specified, a register (IOREG) can be 
specified to point to the start of the data 
field (leftmost position) in the current 
buffer area, or the data can be placed into 
a work area (WORKA) for processing (or 
punching) . In the latter case, DTFCD/CDMOD 
transfers the record from the buffer area 
to the work area or vice versa. The 
capability for reading a card record and 
punching information into the same card 
(CMBND) is also provided if the user has an 
IBM 1442, and IBM 2520, or an IBM 2540 with 
the punch- feed-read (PFR) feature. Many 
data processing installations use the 
stacker selection capabilities made 
available by the following three methods: 



The DTFPR/PRMOD access method provides the 
ability to print a record by issuing a PUT 
macro instruction. The record to be 
printed can be presented to the access 
method via a work area (WORKA) or can be 
placed in the buffer area. Two buffer 
areas (IOAREA1 and IOAREA2) can be 
specified to allow overlap processing. In 
this case, a work area or a general 
register must be used to indicate the 
proper buffer area. Three types of 
printer-form control are provided by the 
access method: 

• CNTRL macro instruction for line 
spacing or page skipping. 

• PRTOV (printer overflow) macro 
instruction for page skipping or 
exiting to a user-supplied routine 
(indicated in the macro instruction) 
that can perform certain end-of-^page 
and/or start-of-page functions. 

• First character control (CTLCHR) that 
can be used where the first character 
of a record may be an ASA or System/360 
control character for line spacing or 
page skipping. 



Paper Tape Files 



1. The user may issue a CNTRL macro 
instruction after a GET or before a 
PUT to select the desired stacker, 

2. First character control (CTLCHR) may 
be used, where the first character of 
a record may be an ASA (American 
Standard Association) or System/360 
control character for stacker 

sel ec t ion , and 

3. The selection for a given file may be 
specified (SSELECT) when the DTF table 
is generated. 



The DTFPT/PTMOD access method provides the 
ability to retrieve a data record from a 
supported Paper Tape device. Two buffer 
areas (IOAREA1 and IOAREA2) can be used for 
overlap processing. In this case, a 
general register must be specified to point 
to the record in the buffer area currently 
being used. This access method also 
handles shifted code for figure shift 
(FTRANS and SCAN) and/or letter shift 
(LTRANS and SCAN) , or nonshif ted code to be 
translated into System/360 and System/370 
code (TRANS) . The user must supply the 
various translation tables needed. 



Console Typewriter 



Magnetic Tape Files 



The DTFCN macro allows reading and writing 
of a record from or to an IBM 1052 
Printer-Keyboard or an IBM 3210 or 3215 
Console Printer-Keyboard by issuing a GET 
or PUT macro instruction. The record may 
be processed in the buffer area or in a 
work area (WORKA) . Only one buffer area 
can be used with this access method. This 
file does not require the use of OPEN and 
CLOSE routines. 



The DTFMT/MTMOD access method provides the 
ability to create or retrieve magnetic tape 
records in sequential order. The file is 
created by indicating via the DTFMT 
parameters that it is an output file 
(TYPEFLE) and then issuing PUT macro 
instructions. If the records are to be 
retrieved, an input file (TYPEFLE) is 
indicated and a GET macro instruction is 
issued. In either case, the records may be 
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processed in a work area (WORKA) or in the 
buffer area by using a general register 
(IOREG). When an input file is to be 
processed, the access method can also 
support the read-backward feature for 
magnetic tape units. 



When an ASCII file is to be processed, 
each record read into the I/O area is 
translated from ASCII to EBCDIC. When an 
ASCII file is to be created, the record in 
the output area is translated from EBCDIC 
to ASCII just before it is written on the 
tape. 



Other optional features that greatly 
enhance the DTFMT/MTMOD access method are: 



• Specifying two buffer areas for overlap 
processing capabilities (I0AREA1 and 
I0AREA2) . 



Alternate tape switching between two 
tape units. 



• Bypassing of checkpoint records on 
input files (CKPTREC) . An ASCII file 
must not contain checkpoint records. 



Other macro instructions allow the user 
to rewind, rewind and unload, execute 
various other magnetic tape device 
functions (CNTRL) , or release (SKIP) the 
remaining records in an input block 
(RELSE) . This can be useful if records are 
grouped by specific categories. An inverse 
function of RELSE allows the programmer to 
truncate or write short blocks of records 
(TRUNC) for an output file. 

In addition to GET/PUT functions, 
DTFMT/MTMOD provides the highly useful 
feature of issuing READ/WRITE macro 
instructions to create a file or retrieve 
records from a work file (WORK) . Overlap 
processing can take place while the I/O 
operation is being performed. The user 
awaits the READ/WRITE operation by issuing 
a CHECK macro instruction that ensures 
completion of the operation. The 
particular features that enhance this 
facility are the NOTE and POINT macro 
instructions. By issuing a NOTE macro 
instruction, the location of the data block 
in the file can then be obtained. POINT 
macro instructions provide the ability to 
reposition to a given block in the file. 
POINTR can position the tape to the block 
indicated, POINTW can position the tape 
after the block indicated, and POINTS can 
position the tape to the beginning of the 
file. 



Sequential Disk 



Records can be created or retrieved and 
updated from a direct access device by 
using the DTFSD/SDMOD access method. The 
file can be created by specifying an output 
file (TYPEFLE) and issuing PUT macro 
instructions. If the records are to be 
retrieved, an input file is indicated 
(TYPEFLE) and GET macro instructions are 
issued. It is also possible to update 
those records in the same location on DASD 
that were retrieved by a GET macro 
instruction. In this case, a PUT macro 
instruction must be issued for the file 
after the GET for the record to be updated 
and preceding the GET for the next record. 
The access method also provides double 
buffering (I0AREA1 and I0AREA2) ability for 
overlap processing. The user can either 
process the record in a work area (WORKA) 
or use a general register to point to the 
record in the current buffer area. Another 
macro instruction allows the user to skip 
the remaining records in an input block 
(RELSE) . This can be useful if records are 
grouped by specific categories. An inverse 
function of RELSE, allows the programmer to 
truncate or write short blocks of records 
(TRUNC) for an output file. The CNTRL 
macro instruction may also be used to seek 
the track address of the next record to be 
processed. In the case of a data cell, 
CNTRL can restore a strip if the user knows 
that processing on it has been completed. 

DTFSD/SDMOD also provides the 
READ/WRITE, CHECK, NOTE, and POINT macro 
instructions described earlier under 
magnetic tape files, although an IBM 
2311/2314/2319/2321 DASD is used as an I/O 
device in this case. NOTE/POINT uses 
cylinder, track, and record identification 
for noting and locating blocks in the file. 
Also, if a NOTE follows a WRITE, the unused 
space on a track can be returned when the 
file is being created or when records are 
to be written in the count, key, and data 
format of DASD. If a POINTR or POINTW is 
issued before a READ or WRITE (UPDATE) , the 
READ or WRITE macro instruction processes 
the block indicated. If a formatting WRITE 
(write count, key, and data) is issued, the 
WRITE macro instruction writes a new record 
after the block indicated. 

Another feature available with this 
access method that can be used in either of 
the two mentioned processing modes, is the 
split cylinder mode. This mode allows two 
or more files to share the same cylinder. 
Each file occupies the same track positions 
through the range of assigned cylinders. 
The technique has the advantage of 
minimizing access-arm movement when cross 
referencing among two or more files that 
perform similar functions. The use of this 
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facility is indicated in one of the job 
control statements (XTENT/EXTENT) needed at 
execution time of the user's program. See 
System Control and System Service listed in 
the Preface for detailed information on the 
job control statements. 



DIRECT ACCESS METHOD (DAM) FILE 
ORGANIZATION 



Great flexibility in reading or writing a 
record from or to a direct access device is 
achieved by the DTFDA/DAMOD access method. 
With the WRITE (AFTER) macro instruction, 
the user may create a file in any manner 
desired. For example, a part number or 
control field can be converted to a DASD 
address using a randomizing algorithm, and 
the record can be written at that disk 
address. Also, the user can create a 
sequential file with keys (control fields) 
to be processed later in a skip-sequential 
fashion. 

In skip-sequential processing, a file 
that has been sorted on a key control 
information field is created in a 
sequential manner. Records are retrieved 
by scanning or searching the file using the 
key of each record desired. In this way, 
only these records are retrieved and the 
job throughput is improved when a large 
percentage of the file is processed. 

Record retrieval is accomplished by 
issuing a READ macro instruction. Two 
types of READ macro instructions may be 
issued for record retrieval. The user may 
read the record by simply supplying the 
track and record location (ID), or by 
supplying the track location along with the 
record key (KEY) to be used for record 
retrieval. Record updating is performed by 
two corresponding WRITE macro instructions 
(ID and KEY). They work in the same way as 
the READ macro instructions. 



whether the I/O operation was 
successful to the problem program in 
the field specified by DTFDA ERRBYTE. 

Three other options, enhancing the 
capabilities of the access method, are: 

1. The ability to utilize the multiple 
track search facility of a DASD 
(SRCHM). 

2. The ability to return the record 
location (the first five bytes of the 
record identification, namely CCHHR) 
when retrieving a record by its key 
(IDLOC). These features facilitate 
skip-sequential processing. For 
example, by issuing a READ (KEY) macro 
instruction and starting at the 
beginning of the file, the direct 
access device searches multiple tracks 
until the record is found. The record 
location is returned and is used as a 
reference point in starting the search 
for the next record to be retrieved. 
In this manner of processing, only the 
required records are read, whereas in 
the normal sequential mode of 
processing, all records are read even 
if they are not all processed. 

3. The ability to seek ahead by issuing a 
CNTRL macro instruction (or restore a 
strip to an IBM 2321 Data Cell) and 
then continue normal processing or 
issue other I/O device macro 
instructions . 

When creating a file using the WRITE 
(AFTER) macro instruction, the access 
method automatically maintains the amount 
of space available on each track on which 
the records are stored along with the 
address of the last record on each track 
(provided the DASD has been properly 
initialized) . This access method does not 
provide blocking and deblocking facilities. 
They must be performed by the user. 



In addition to the READ/WRITE macro 
instructions, there is a WAITF macro 
instruction. This macro instruction is 
issued after each READ/WRITE. The WAITF 
macro instruction serves a two-fold 
purpose : 

1. It allows overlap processing or 
issuing of another I/O device macro 
instruction (within the limitations of 
the system configuration) while the 
present I/O operation is taking place, 
and 

2 . It communicates termination of the 
READ/WRITE operation with which it was 
associated, and returns any 
error/status information indicating 



Random Addressing Techniques 



In addition to the specification of the 
DTFDA and DAMOD macros, the problem 
programmer must supply the DASD address of 
the record to be read or written before 
issuing each READ/WRITE imperative macro. 
The following discussion presents various 
methods for determining a DASD address from 
a record control field. 

File addressing involves the file of 
records that must be stored and retrieved 
in a data processing system, and the direct 
access storage device itself. The data 
records that must be stored in a direct 



< 
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access storage device are usually 
identified by a control field, such as part 
number, and employee number, normally, the 
numbers or characters in the control field 
are unevenly distributed. For example, a 
seven-positioned control field may be used 
to identify 25,000 items in a parts master 
file. However, with a seven- position 
number, it is possible to identify ten 
million items. In this example, only 0.25% 
of the available numbers are used. 



The direct access storage devices, on 
the other hand, are usually composed of 
physical locations that are identified by 
an evenly distributed set of numbers. The 
addressing problem converts an unevenly 
distributed set of numbers to an evenly 
distributed sequential set of numbers 
within the address limits of the direct 
access device. Many addressing techniques 
have been developed to accomplish this 
task. In choosing a technique for address 
conversion, it is important to remember 
that an ideal distribution of control 
fields is a completely uniform one. 
Uniform distribution means that the 
difference between any pair of successive 
control fields taken in ascending order is 
constant. 



The worst distribution of control fields 
is a random one. There is no way to 
transfer from random keys to addresses with 
better than random distribution. In 
practice, purely random control field sets 
and completely uniform ones are rare. A 
data file is likely to have control fields 
that distribute in groups or clusters of 
irregular length and separation. This kind 
of grouping of numbers introduces a degree 
of uniformity. The irregular length and 
separation of the number groups implies a 
degree of randomness. A well chosen 
conversion technique produces an address 
set that reflects both elements and has a 
distribution intermediate between random 
and uniform. To be ideal for use in direct 
access storage devices, the conversion 
technique should produce a unique storage 
address for every record in a file. This 
is seldom possible. Most control-field 
conversion routines result in assigning 
some address to more than one record. 
These duplicate addresses are sometimes 
referred to as synonyms. The selected 
conversion routine should convert the 
control fields (keys) of the records in a 
data file to a series of addresses with a 
minimum number of synonyms and within the 
desired storage address range. The 
following sections discuss briefly the most 
successful conversion routine, followed by 
a discussion of synonym handling. 



Random Addressing Formula 



The simplest method of file organization is 
that in which a unique DASD address is 
obtained from the control data of each 
record. This is referred to as the random 
addressing method. If the control numbers 
of a set of data records in a file are 
consecutive numbers without gaps, they may 
be converted to DASD addresses by simple 
arithmetic. For example, if the account 
numbers for a customer file run from 10000 
to 17563 (75 64 account numbers) , and ten 
account records can be stored on each disk 
track, 757 tracks are needed. By 
subtracting 10,000 from an account number 
and then dividing by 10, a numeric address 
in the range 000 to 756 is obtained. To 
place this file on a 2311/2314/2319 disk 
drive, starting at track address 1200 
(cylinder 120 head 0), a constant 1200 is 
added to the quotient and a constant (1) is 
added to the remainder. This constant (1) 
is required because record zero (R0) of 
each track is reserved to facilitate the 
handling of defective recording areas that 
may occur during the life of the disk pack. 
Using this approach, a record containing 
the data for account number 16349 would be 
stored at track reference 1834 in 
record-reference ten, calculated as 
follows: 



16349 - 10000 = 6349 



6349 ; 10= 634 with remainder 9 



634 + 1200 = 1834 = track reference 



9 (remainder + 1) = 10 = record reference 



When processing this file randomly, any 
record can be found with a single seek. 
When it is possible to process 
sequentially, only one seek is needed per 
cylinder. Record retrieval time is thus at 
a minimum. This is an optimum situation, 
and it rarely occurs in actual practice. 



Normally, the control data of a file of 
records can seldom be used directly as DASD 
addresses. If a file does not have control 
fields that can be used directly as DASD 
addresses, it is sometimes possible to 
preassign addresses. For example, the item 
number 513XP could become 513XP-13472, that 
could then be converted to a track and 
record reference. 
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Prime Number Division 



1394570307 
of 5825. 



9973 = 139834 with a remainder 



If the control fields of a file of records 
are not consecutive or contain numerous 
unused numbers, as is usually the case, the 
random addressing technique under the topic 
Random Addressing Formula makes inefficient 
use of storage locations. All possible 
numbers are assigned locations, and those 
numbers not used leave empty record areas 
in the storage unit. Files established 
with control numbers composed of coded 
information usually have a much higher 
potential range of items than is required 
for storage. To handle this situation, 
initial conversion is made on the control 
numbers to reduce the range to a practical 
size. This conversion is often referred to 
as randomizing. 



This remainder is operated on as in the 
example, under the topic Random Addressing 
Formula , assuming 10 records per track. 



5825 v 10 = 582 with a remainder of 5, 



To load the file starting at track address 
1100, add 1100 to 582 for a sum of 1682. 
The track reference for this record is 
1682, and the record is the sixth record on 
the track (remainder of 5 + 1 = 6). 



To summarize prime number division: 



Randomizing generally refers to the 1. 
techniques developed to convert a set of 
control numbers with numerous unused 
numbers to a tightly packed set, to result 
in very few unused storage areas. There 
are many techniques used for this 
conversion of numbers, a few being: 
folding, extracting, squaring, and radix 
transformation. One method, sometimes 
called prime number division* or divide 
remainder, is adaptable and usually 2. 

satisfactory for converting a file of 
numbers . 



Select a divisor equal to or greater 
than the number of records to be 
stored (10 to 20% greater is 
recommended) . The best divisors are 
primes. Even numbers or multiples of 
five should never be used - divisors 
must end in 1, 3, 7, or 9. The 
divisor is called the range. 



Divide the control number by the range 
and use the remainder to generate the 
track address. 



To illustrate the prime number division 
technique, suppose the customer file in the 
example under the topic Random Addressing 
Formula used a coded control number of ten 
digits. The first three could be a 
geographical code (branch office number) , 
the next two could describe the nature of 
the business, the next one could be a 
size-of-customer code, and the final four 
could be sequentially assigned within 
class. 

Thus, account number 139 457 0307 would 
be the 307th account assigned branch office 
139. It would belong to a customer-of-size 
code 7 in industry class 45. Because this 
ten-digit number cannot be used efficiently 
to describe 7564 accounts, it is converted 
by dividing by the closest prime number to 
the number of storage locations available. 
Assume 10,000 locations available, then 
divide by 9973. The remainder serves as 
the control number and a technique similar 
to the example under the topic Random 
Addressing Formula calculates a track and 
record reference. 



Prime number division always works; that 
is, it always converts control numbers into 
the desired range because in division, the 
remainder is always less than the divisor 
and the highest valued remainder is the 
divisor- 1. Dividing any number, no matter 
what size, by a desired range, always 
produces remainders in the desired range. 
Using a prime number as the divisor usually 
results in relatively few duplicate 
remainders, and therefore relatively few 
address synonyms. 



A prime number is not always the best 
choice of divisor for a given set of keys. 
Also, it is not necessarily true that all 
primes produce equally good results. 
However, primes avoid serious 
maldistribution and may be safely used with 
little analysis of the control field set of 
the data files. 



* A prime number is a number divisible only 
by itself, or one. 



126 DOS System Programmer's Guide 



Synonym Records 



The transformation of record control fields 
to direct access storage device addresses 
usually produces some synonym records. 

The file organization used with a data 
file employing indirect addressing 
(addresses converted by a random addressing 
formula) must be able to accommodate the 
synonyms or duplicate addresses. 

The first consideration in organizing 
the file is sometimes called the packing 
factor. The number of synonyms produced by 
a random addressing conversion routine can 
be reduced by assigning more DASD storage 
space than is actually required by the 
file. The percentage of the file area 
actually used for record is called the 
packing factor. The packing factor for an 
efficiently organized file can vary from 
65% to 95%. A packing factor of 80% 
usually proves to be a good starting point. 
After all efforts have been made to design 
a file conversion technique with few 
synonyms, an approach to handling the 
remaining synonyms must be chosen. 

One such technique is often referred to 
as the chaining method. As each record is 
read into the computer for loading into a 
direct storage access device, its control 
field or key is converted to a physical 
address. These converted addresses are 
called home addresses. 



and another read command is issued using 
this address. The process is repeated 
until the desired record is found. 



Record Reference 



Overflow 
Address Field 



CC HH R 
73 06 1 


CC HH R 




74 02 3 


74 02 3 




74 09 2 


74 09 2 




69 06 4 


69 06 4 




74 35 6 


74 35 6 




Blank 



CC - cylinder 
HH = head 
R = record 

Figure 2.17. Direct Access Address 
Chaining 



Note ; The home addresses discussed here 
are not directly related to the track home 
address used to control the physical 
operation of the DASD. These home 
addresses are related to the record 
identifier (ID) associated with DAM. 



Two other techniques that solve the 
synonym problem are similar in concept to 
the chaining method but do not require a 
chaining field to be present in each 
record. 



The first record converted to a 
particular address is stored in the home 
address location. The additional records 
converted to this address are stored in 
synonym locations. The address of the 
first synonym location is stored in the 
home address location. The address of the 
second synonym location is stored in the 
first synonym location, etc. Chaining 
requires that in the home address and all 
synonym locations, space be reserved for 
the address of the next location or link in 
the chain (Figure 2.17). 

Retrieval of records is accomplished by 
converting the control information (record 
key) to the home address. The record in 
the home address location is read into main 
storage, and its control information is 
compared to that of the record being 
sought. If the control fields are not 
equal, the address of the first overflow 
record is extracted from the home record. 



1. P reassigned tracks synonym technique. 
When there is not room to store a 
record in its home location, a 
specific preassigned synonym track is 
used. The synonym track (s) should be 
defined to be in the same cylinder 
containing the home location to reduce 
the number of seeks required to locate 
a record. 

2. Consecutive spill synonym technique. 
When a synonym occurs, a sequential 
search is made starting at the next 
record within the cylinder until an 
empty record storage location is 
found. If the last track in a given 
cylinder overflows, a return is made 
to the first track. This technique 
does not require the use of a chaining 
field, nor is a seek required to 
locate the synonym record (must be on 
same cylinder) . 
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DASD Address Specification For Read/Write 
Operations 



The direct access method requires DASD 
addresses for all read/write operations. 
These addresses may be supplied in one of 
two ways: as an actual physical address 
(MBBCCHHR) or as a relative track address 
(see Relative Track Addressing ) . 

The actual physical address can be 
specified as an 8-byte binary address (see 
Figure 2.18) in the form MBBCCHHR. These 
8-byte addresses are used either as the 
starting point for a search on record key 
or as the actual address for a READ or 
WRITE ID. When searching for a record key, 
the programmer may specify that the search 
be only within the specified track, or from 
track to track, starting at the address 
given and continuing either until the 
record is found or until the end of the 
cylinder is reached. 



When the ID returned is that of the next 
record, the system obtains the ID by 
chaining to a read-count command. This 
command skips to the next track if the 
record read or written was the last 
currently on the track. The system does 
not read the next ID if the end of a 
cylinder is reached. In this case, it adds 
one to the CC portion of the previous ID, 
forces the HH portion to 0, and forces R to 
1 for a 2311, 2314, or 2319 file. For a 
2321 file, it adds one to the high order H, 
forces the low order H to zero, and forces 
R to one. An overflow from the high order 
H increases the low order C by one, forces 
both Hs to zero, and forces R to one. 
Subsequent overflows of address locations 
cause increases in the next higher 
positions of the addresses. (It is the 
user's responsibility to check the validity 
of the address returned in IDLOC. ) 
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Address Specified by 
SEEKADR = Name 



Required for Record 
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Figure 2.18. DASD Address Formats 



For certain types of operations, the 
system can be requested to return the ID 
(CCHHR) of the record read or written or of 
the next record following the one read or 
written. The programmer can place these in 
the 8-byte address field to either READ or 
WRITE a new record or to update the one 
read. For example, to delete a record from 
a random file with keys, the programmer can 
randomize the record key to a starting 
location, search on key to read the record, 
and then use the ID returned to write a 
blank or zeroed record (key and data) back 
into the same location. The descriptions 
of the READ and WRITE macro instructions 
explain when the ID can be returned and 
whether the ID returned is that of the same 
or of the next record. See Data Management 
Concepts listed in the Preface for a 
description of these macros. 



Relative Track Addressing 



The required DASD addresses may also be 
given as a relative address. This address 
is then converted by IOCS to the actual 
physical address (see Figure 2.18). 
Relative track addressing is more 
convenient to use than the actual physical 
address for the following reasons: 

1. The data in the file appears to be one 
logically-continuous area, although it 
may be physically noncontiguous. 

2. The user needs to know only the 
relative position of the data within 
the file; its actual physical address 
is not required. 

The relative address may be specified by 
the user in either of two formats: 
hexadecimal (in the form TTTR), or zoned 
decimal (in the form TTTTTTTTRR) . 

In both the hexadecimal and zoned 
decimal format, the Ts represent the track 
number relative to the start of the data 
file, and the Rs represent the record 
number on that track. The hexadecimal 
format requires 4 bytes, while the zoned 
decimal format requires 10 bytes. Relative 
track addressing is implemented through the 
DTFDA macro. Parameters in this macro 
specify the number of extents in the file, 
the form of relative addressing used 
(hexadecimal or zoned decimal), and other 
required information. For specific 
information on the implementation of 
relative track addressing, see the 
Supervisor and I/O macros listed in the 
Preface. 
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INDEXED SEQUENTIAL FILE MANAGEMENT SYSTEM 
(ISFMS) 



The DTFIS/ISMOD facility is both an access 
method and a DASD file organization 
technique. Facilities are provided for you 
to create a file, add new records in any 
order to a previously created file, and 
retrieve all records in the file either 
randomly or sequentially. 

The track hold facility is also provided 
for protecting DASD tracks that are 
currently being processed. Track hold 
prevents two or more programs from updating 
the same record at the same time provided 
all the programs use the facility. 

The file is created in ascending 
sequential order from the input that has 
been previously sorted on the record keys. 

As the file is created, an index 
hierarchy is developed. The (lowest level 
is called the track index and occupies the 
first track (in the case of an IBM 2321, 
one or possibly more tracks) of each 
cylinder that is contained in the file area 
called the prime data area. This index 
includes a pair of index entries for each 
track of the cylinder containing the user's 
data records. The first entry of each pair 
indexes the highest record key on the 
appropriate track being referenced. The 
second entry locates overflow records that 
can occur from that track when new records 
(additions) are added to the file. 



The second level of index, called a 
cylinder index, is generated on a DASD area 
separate from the prime data area. An 
entry is made in the cylinder index for the 
highest record key of each cylinder in the 
prime data area, and each entry points to 
the track index on the appropriate 
cylinder. 

A third, optional level of index, the 
master index, is generated in the same area 
as the cylinder index and precedes it. The 
master index has an entry for the highest 
key on each track within the cylinder index 
area. For a small file, this level of 
index is generally not needed because 
searching a cylinder index of two or three 
tracks is as fast as searching the master 
index and then the cylinder index. 

An index entry is composed of a key and 
an address. The track index is composed of 
two types of entries, a normal entry and 
overflow entry for each prime data track 
within that cylinder. In the example 
illustrated in Figure 2.19, the normal 
entry indicates that the highest key on 
track 1 is 8, and the address is at the 
beginning of track 1. The overflow entry 
indicates the same key after loading as the 
normal entry. The address of hexadecimal 
Fs indicates no entries for this track in 
the overflow area. 



Note ; If the track index does not occupy 
all of track 0, track also contains data 
records. 
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Figure 2.19. Example of Track Index 



If record 7 is added to the file as 
illustrated in Figure 2.20, record 8 would 
be forced into the overflow area, and 
record 7 would be the highest record on 
track 1. In this case, the key of normal 
entry is changed to 7, and the address of 
the overflow entry indicates the location 
of record 8, which is on track 8 record 1. 
No other changes to the indexes are 
required. 

The cylinder overflow control record 
(COCR) , that is maintained in the data 
portion of record zero, would indicate that 
no records were in the cylinder overflow 
area after loading. After the addition of 
record 7, it would be updated to indicate 
that the last record in the cylinder 
overflow area was on track 8, record 1. 

The cylinder index indicates that record 
32 is the highest key on the cylinder, and 
its address points to the track index. The 
cylinder index has its own extents that 
must be defined at job control time. These 



extents must be outside the limits of any 
data extents. (Note that at least two sets 
of extent information must be defined at 
job control time. These would define a 
data extent and a cylinder index extent.) 
If the file exceeds one disk pack, 
additional data extents are provided, and 
at the user's option, an independent 
overflow area extent may be defined. The 
cylinder index extent must be on-line when 
the file is processed. It may be on the 
same pack as the data file, or it may be on 
a separate pack. 

Because the file is sequential with a 
hierarchy of indexes, it is called an 
indexed sequential file. The indexes 
provide direct reference to records, 
allowing their random retrieval with a 
minimum of search time. The sequential 
order of the data records, coupled with the 
ability to reference overflow records in 
sequence via the track index, provides 
sequential retrieval capability. The 
indexed sequential method consists of four 
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Figure 2.20. Example of Track Index after Addition to File 



basic functions that provide capabilities 
for creating a file, adding new records to 
it, and retrieving the records. A 
description of each function follows. 



Loading an Indexed Sequential File 



A file and its associated indexes are 
created by the load function. In addition 
to the DTFIS macro instruction specifying 
IORODT=LOAD, there are three other macro 
instructions used to create the file. The 
first one to be issued is a SETFL macro 
instruction (set file load mode) that does 
the initializing needed for file creation. 
When the WRITE (NEWKEY) macro instruction 
is issued, the key and data record placed 
by the user in a work area (WORKL) are 
moved to an output block in the buffer area 



(IOAREAL) and then written in the prime 
data area. The appropriate index entries 
are also made. After the user has 
presented all the data records needed to 
create the file, an ENDFL macro instruction 
(end file load mode) is issued to terminate 
the load. 

Facility is provided for protecting DASD 
tracks that are currently being accessed. 
For ISAM, the hold applies to both data 
records and index records. Because track 
hold cannot be performed on a LOAD file, 
HOLD=YES cannot be specified when 
IOROUT=LOAD. 

Facility is also provided to extend the 
file by adding new records higher in 
collating sequence than the current last 
(high) record in the file. Using the same 
user program, this can be done by 
specifying ISE in the DLBL/DLAB job control 



Section 2: Data Management 131 



statement (required at execution time of 
the user's program) to indicate a file 
extension is to take place. 



The same macro instructions that load a 
file originally can be used to extend the 
file. If it is necessary to increase the 
size of the file to contain records with 
keys higher than the last key on the 
original file, the records can be loaded at 
the end of the file. A job control 
XTENT/EXTENT statement extends the upper 
limit of the prime data area of the file so 
that the new records can be loaded into the 
file. (Overflow area is not required 
because the file is merely extended further 
on the DASD. ) 



Adding Records to the File 



The add function provides the ability to 
insert new records in the file. In 
addition to the DTFIS macro instruction 
specifying IOROUT=ADD, there are two other 
macros used for adding records to a file. 
The first is a WRITE (NEWKEY) , that 
initiates the addition process (searching 
the indexes, etc.) and returns control to 
the user to allow overlap processing. To 
complete the addition operation, a WAITF 
macro instruction must be issued. This not 
only ensures that all necessary I/O 
operations have been completed but also 
returns status conditions indicating any 
abnormal operation. When additions are 
made to the file, the user presents the key 
and data record to be added in a work area 
(WORKL). A search is made through the 
index structure to determine where the 
record is to be inserted in the file. The 
record is either inserted in key sequence 
in the prime data area, or placed in the 
overflow area by use of a chaining 
technique that maintains the proper 
sequence of the file. 



Two overflow area options that may be 
used in any combination are provided. One 
option allows the user to specify that one 
or more tracks be reserved at the end of 
each cylinder to store overflow records 
(CYLOFL) . The second option allows an 
independent overflow area separate from the 
prime data area to be reserved for storing 
overflow records. The first option has the 
advantage of reducing access time for the 
retrieval of overflow records associated 
with a given cylinder. The second option 
has the advantage of utilizing DASD space 
more efficiently. 



Random Retrieval 



The random retrieval function is used for 
random retrieval and updating of records. 
In addition to the DTFIS macro specifying 
either IOROUT=RETRVE or IOROUT=ADDRTR and 
TYPEFLE=RANDOM, there are three other 
macros for randomly retrieving and updating 
records. The first of three macro 
instructions to be issued for this purpose 
is a READ (KEY) . The READ macro 
instruction performs a search of the 
indexes, using the key of the requested 
record (KEYARG) provided by the user as the 
search argument. While the I/O operations 
that perform this function are taking 
place, control returns to the user to allow 
overlap processing. To complete the READ 
function and receive the record, the user 
must issue a WAITF macro instruction. If 
the operation is completed successfully, 
this macro instruction either places the 
record into a work area (WORKR) or points 
to the starting location (leftmost 
position) of the record within the buffer 
area by using a general register (IOREG). 
If the operation was not successful, 
indications of the resulting abnormal 
conditions are given in the filenameC 
status byte in the DTF. 

If the user wants to update and return 
the record to the file, he must issue a 
WRITE (KEY) macro instruction. The WRITE 
follows the READ of the record to be 
updated and precedes the READ for the next 
record. Again, processing can overlap 
execution of the WRITE instruction. To 
complete the operation, the user must issue 
a WAITF macro instruction. 



Sequential Retrieval 



The sequential retrieval function makes it 
possible to sequentially retrieve and 
update records. In addition to the DTFIS 
macro instruction specifying either 
IOROUT=RETRVE or IOROUT=ADDRTR and 
TYPEFLE=SEQNTL , there are four other macros 
for sequentially retrieving and updating 
records. The first of four macro 
instructions to be issued for this purpose 
is the SETL (set lower limit) , that locates 
the starting point where retrieval begins. 
This macro instruction provides four 
methods of starting retrieval: 

• From the beginning of the file (BOF) 

• At any record location in the prime 
data area (ID) 

• With any record in the file by 
supplying the key of the desired 
starting record (KEY) 
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• With the first record of a group of 
records in the same class by supplying 
the generic key for that class; a class 
being any group of records that 
contains identical control information 
in the first few high-order bytes of 
the record keys (GKEY, a key equal to 
or lower than the first record of the 
desired group) 

After the SETL has been successfully 
executed, the user can issue GET macro 
instructions to retrieve each record in the 
file in key sequence. The record can be 
placed in a work area (WORKS) , or a general 
register can be used to point to the 
starting location of the record in the 
buffer area. If the user wants to update 
the record and return it to the file, he 
must issue a PUT macro instruction. This 
POT must follow the GET of the record to be 
updated and precede the GET of the next 
record. After all of the desired records 
have been processed, the sequential 
retrieval function is terminated by issuing 
an ESETL macro instruction. This process 
of issuing the SETL, GET, PUT, and ESETL 
macro instructions can be repeated as many 
times as desired. By combining the macro 
instructions of the sequential retrieval 
and load functions, the file can be 
reorganized. The user can retrieve the 
current file in its proper sequence (both 
prime data area records and the associated 
overflow records) and recreate the file in 
a new prime data area. 



CHOOSING THE RIGHT FILE ORGANIZATION AND 
RETRIEVAL METHOD 



The flexibility of a disk system lends 
itself to several different file 
organization and processing methods. It is 
important, therefore, to analyze each file 
and the program (s) that process it to 
ensure that the chosen method constitutes 
the optimum solution with respect to the 
data processing requirements of the 
installation . 

In many cases, the type of organization 
and processing best suited to a file is 
immediately evident. However, some 
applications may require additional study, 
because of their complexity, their unusual 
processing requirements, or because of the 
wide range of processing programs that use 
a file. This is an important aspect of 
planning for a data processing system. 
Decisions in this area may affect system 
configuration requirements and should be 
made before programming begins. The 
general level of efficiency of the data 
processing installation may be affected. 



There are no absolute rules for the 
resolution of an uncertain situation 
regarding the organization and retrieval 
alternatives. However, there are several 
criteria that may provide an indication of 
the optimum solution. 



Criteria 

The following items form a basis for a 
decision concerning the organization of a 
file. 

File Activity : Activity refers to the 
number of records in a file for which there 
are transactions. This is usually 
expressed as a percentage. 

For example, 10% activity in an 
inventory file means that, during some 
specific period, there are transactions to 
be posted to 10% of the records contained 
in the inventory file. As the activity 
increases, sequential processing becomes 
more efficient. Sequential processing 
implies either sequential or indexed 
sequential organization. Activity implies 
batch processing. This means that, 
transactions do not need to be posted the 
moment they occur. In fact, the time that 
may lag between the occurrence and the post 
may vary from a few hours to weeks or even 
months, depending on the application. 

Although the activity of a file is 
measured over time, there are applications 
where transactions cannot be batched. An 
example would be an on-line inventory file 
where the transactions would have to be 
handled as they occur. 

Low activity may justify random instead 
of sequential retrieval. 

Another important consideration involves 
the level of activity when sequential 
processing becomes more efficient than 
random processing. In order to make this 
evaluation, you must know: 

• the record length and the blocking 
factor 

• the average number of additions to the 
file 

• whether the input is sorted. 

If the Indexed Sequential File Management 
System is being evaluated for random or 
sequential processing, you must also know: 

• the average time required for access to 
the cylinder index. 
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• which overflow options were chosen. 



• if the resident cylinder index facility 
has been selected, and if so, what 
percentage of the cylinder index can be 
main storage resident. 

During random processing with ISFMS it is 
advantageous to presort the transactions if 
the resident cylinder index facility has 
been implemented. 



File Volatility ; Volatility refers to the 
number of additions to and deletions from a 
file. First, consider the effect of making 
additions to or deletions from a 
sequentially organized file. Two files 
must be defined, and the operation must be 
handled as it would be with tape, reading 
from the input file and writing to the 
output file. With high volatility (that 
is, many additions and deletions), indexed 
sequential organization provides a 
practical solution. One of the advantages 
of an indexed sequential file is that 
additions and deletions can be handled 
without copying the file. However, as the 
number of additions increases, the 
efficiency of processing an indexed 
sequential file decreases. Additions cause 
records to be placed in overflow areas. 
Retrieval of these records in the collating 
sequence of the file requires more time 
than simply retrieving the records from 
contiguous tracks of the original file in 
their physical sequence. This is due to 
the additional access-arm movement required 
to read from the separate overflow area(s) 
and additional reads even when cylinder 
overflow is used. 

With relatively few additions, the 
decrease in efficiency is minimal. 
However, there is a point at which it 
becomes advisable to reorganize the file. 
Reorganization means building a new indexed 
sequential file from the old one and, in 
the process, physically excluding all 
records that are tagged for deletion. In 
the same operation, all records in the 
overflow area are merged into the main 
file. At this point, the cycle begins 
again. Processing with the reorganized 
file is highly efficient. As additions and 
deletions occur, this high level of 
efficiency gradually diminishes, until we 
reach a point where reorganization again 
becomes advisable. 

Additions to a direct access file do not 
necessitate the creation of a new file as 
they do for sequential organization. 
However, as the DA file extents fill up, 
the randomizing algorithm and its 
corresponding synonym processor is more 
heavily taxed. 



Therefore, the following considerations 
should be made: 

• At what point is it most advantageous 
to reorganize an indexed sequential 
file? 

• What level of volatility excludes 
indexed sequential organization as a 
practical method of file organization? 

• What are the operational considerations 
for each method of organization? 

Many variables must be considered to answer 
these questions. It is impossible to 
provide direct answers except in terms of a 
specific file and a well defined 
application. 

File Size ; The user must consider the fact 
that his on-line capacity is limited. 
Three important file organization 
considerations are affected by the size of 
a file: 

1. An indexed sequential file must be 
entirely on-line for any type of 
processing. 

2. A sequential file on disk may be 
written on any number of packs, that 
are then mounted and processed 
consecutively. Each disk pack may be 
mounted as needed but the manual 
intervention that is required is time 
consuming . 

3. A direct access file must be entirely 
on-line for any type of processing. 

The fact that an indexed sequential or 
direct access file must be entirely on-line 
whenever it is to be processed imposes 
obvious physical restrictions on maximum 
file size. We have talked about the 
necessity of periodically reorganizing an 
indexed- sequential file. The user must 
also consider how this requirement affects 
file size. For the purpose of file 
reorganization, two files must be defined: 
the file to be reorganized and the newly 
created file. If the user's installation 
does not include tape units, and if the 
user does not want to punch his entire file 
into cards, the on-line disk capacity must 
be sufficient to accommodate both these 
files. If the installation includes tape 
units, the reorganization can be 
accomplished in two steps. The first 
program sequentially retrieves records from 
the indexed sequential file that is to be 
reorganized and creates an output file of 
these records on tape. The second program 
uses this tape file as input and writes the i 
reorganized (output) file on disk. Thus, \ 
the maximum size of an indexed sequential 
file can be doubled by using magnetic tape 
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as an intermediate storage medium. (An 
alternative would be a series of disk 
volumes forming a sequential disk file and 
sequentially sharing the same drive.) 
Figure 2.21 illustrates organization on a 
disk- tape system. 
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Disk/Tape System 



It is possible and frequently desirable 
to divide a large indexed sequential file 
into several smaller files. Although this 
approach reduces the flexibility of 
processing the records, it provides many 
significant advantages for applications 
with a low activity rate. 

In many cases, if a disk file exceeds 
the size limitations imposed by indexed 



sequential organization it can be organized 
sequentially. 



First consider a DOS system with two 
disk drives. In this case, a sequential 
file may be contained on any number of 
packs. When a processing program reaches 
the record with the highest control 
information of the disk packs on-line, it 
stops. The operator can then mount the 
next pack on the same drive and the 
operation can be resumed, when a 
multivolume file is assigned to a disk 
drive, all subsequent volumes (disk packs) 
of the file must be mounted on the same 
drive. 



Most sequential files are altered 
periodically by additions and deletions. 
In this case, two drives should be used 
with multivolume files; one for the input 
file volumes and one for the output file 
volumes. Each time the end of the 
available capacity of a pack on either 
drive is reached, the system issues a 
message on the console to alert the 
operator that it is time to change disk 
packs. 



Consider the one- drive system. In this 
environment, multivolume sequential files, 
that are retrieved only, or retrieved and 
updated, can be processed on the single 
drive. If records are to be added and 
deleted, two files are involved: one input 
and one output file. Both files must be 
completely contained in one volume and the 
area available to each of the two files 
must be large enough to accommodate any net 
increase in file size brought about by 
subsequent additions and deletions. The 
single-drive system does not readily 
accommodate multivolume sequential files to 
which additions and deletions must be made. 

This limitation can be circumvented by 
dividing a large file into smaller 
segments, each of which can be defined as a 
complete file and accommodated within the 
available portion of a single pack. This 
area is less than half a pack. The user 
must treat these segments consistently as 
separate files, going through the normal 
cycle of job-to- job transition and program 
retrieval as each volume is mounted. This 
approach, while solving one problem, may 
create others. If totals or statistics 
must be computed when processing the entire 
file, a means must be devised for carrying 
results forward from one volume (file 
segment) and one program to the next. This 
can be accomplished but it introduces an 
additional programming complexity with 
which the user of the two- drive system need 
not be concerned. 
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Response Time : One of the important 
advantages of a computer system with a 
direct access storage device is the ability 
to answer inquiries. Not all applications 
require the use of an inquiry capability. 
In some data processing installations, 
there are no inquiry applications at all. 
Where it is required, response time to an 
inquiry is a critical consideration. The 
less critical the response time, the 
greater the choice of organization and 
retrieval options. 

The user should consider the following: 

• Can the answer to an inquiry wait until 
the next batched, sequential updating 
of the relevant file? If it can, then 
inquiries become an additional 
transaction type and are processed 
sequentially with all other 
transactions against the file. File 
organization, in this case, could be 
either sequential or indexed 
sequential. If the response provided 
by this method is not fast enough, 
random access is required. 

• Can the answer wait until the end of 
the present computer run? If so, the 
relevant file is mounted at the 
completion of the current job; the 
inquiry program is loaded; and the file 
is processed to produce the required 
answers. Obviously, the time delay 
involved here varies considerably 
depending on the job that is in 
progress when the inquiry arrives. 



Random Retrieval Consideration : Many files 
that could be organized sequentially are 
organized as indexed sequential files to 
facilitate system design. It is often 
possible to reduce the number of peripheral 
operations by using random retrieval from 
an indexed sequential file. This is true, 
for example, of files that have fields 
which are used in several jobs. 

As an example, assume that invoice 
summary cards are to be listed in the 
sequence of invoices. Further assume that 
the cards do not contain customer names, 
but that these names are required in the 
listing. Customer names may be obtained 
from the customer master file by random 
retrieval (if that file is organized as an 
indexed sequential file) or by sequential 
retrieval. Note that, in the latter case, 
the invoice summary cards must first be 
sorted into customer number sequence. 
Figure 2.22 illustrates the two solutions 
and shows the additional steps required if 
the customer master file is organized 
sequentially. 



The example for the sequential file is a 
typical procedure for sequential processing 
equipment. If this job were run 
frequently, the system design 
considerations would probably preclude the 
use of a sequential file organization. 

The considerations previously proposed 
establish criteria for choosing the 
organization and retrieval method for a 
file. In the subsequent paragraphs, these 
criteria are applied to a number of sample 
files. 



Sample Files 



This part illustrates the choosing of file 
organization and retrieval methods for some 
typical sample files. 

The characteristics of the sample file 
are chosen arbitrarily. Different 
characteristics could be attributed to 
files of similar functions. The examples 
are furnished to demonstrate the 
application of the criteria we have just 
discussed to certain specific file 
characteristics; and to show, under these 
circumstances, the optimum organization and 
retrieval methods. 

Example 1 

File: table file 

Characteristics : the file is stable and 
requires few changes and infrequent 
additions and deletions. When alterations 
are required, the source card file is 
altered and the file is reloaded onto disk. 
Normal processing involves retrieval only. 

Organization: sequential 



Example 2 

File: payroll file 

Characteristics: the file has generally 
low volatility; and a relatively low level 
of additions and deletions. However, there 
is a high activity rate. Processing for 
each pay period involves updating of a high 
percentage of the year-to-date master 
payroll information. Batching of 
transactions, (time cards, changes, etc.) 
is normal. Fast response to inquiries is 
not required. 

Organization: sequential 
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EXAMPLE A : INDEXED - SEQUENTIAL ORGANIZATION 
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Figure 2.22. Indexed Sequential Versus Sequential File Organization 
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Example 3 

File: wholesale inventory file 

Characteristics: the file has moderate 
volatility and moderate activity. Normal 
transactions may be batched for posting 
once or twice a day. Recurring stock 
status, activity, and reorder reports are 
sequential. Response to inquiries 
concerning availability and stock level is 
required within one hour. 

Organization: indexed sequential 



upon many factors. These factors must be 
analyzed for each file in any one 
particular application. Often, more than 
one organization scheme can be considered 
for the same file. In one application, 
records could be processed purely at 
random; in another, the same records could 
be processed in sequence by various control 
fields. For example, records within a file 
might be processed at random during an 
updating run and sequentially within 
certain groups such as branch office or due 
date when producing reports or billing. A 
file such as this would be analyzed to 
determine whether it should be organized: 



Example 4 

File: on-line inventory, parts 

Characteristics: the file has a low 
volatility but a high activity. 
Transactions are processed as they are 
received. Responses to inquiries 
concerning availability and stock level is 
required within 2 minutes. Recurring stock 
status, activity, and reorder reports are 
sequential but are only produced bimonthly. 

Organization: random 

Example 5 

File: accounts receivable file 

Characteristics: the file has low 
volatility and low activity. Transactions 
are combined in batches for daily posting. 
Billing is cyclic, statements are written 
throughout the month by sequentially 
retrieving records from the file between 
specific limits. Inquiries are processed 
twice daily. 

Organization: indexed sequential 



Summary 

The method of organization best suited to a 
particular file of disk records depends 



1. Randomly, thus keeping process time at 
a minimum during one run but 
destroying the advantage of the 
sequential nature of the other. 



2. Sequentially, thus minimizing the time 
required to produce reports but 
increasing updating time. 



Randomly for updating, and then sorted 
into sequence for reports. 



The decision would depend on the nature of 
the file. Other considerations might be: 



1. Can transactions be batched and sorted 
before processing, or must they be 
processed as they occur? 



Is the activity distributed throughout 
the file in such a manner as to 
warrant passing the entire file when 
updating? 



3. Would the processing time saved by 
sorting warrant the time and effort 
required? 

Questions of this kind apply to each file 
in an installation. In choosing 
organization methods, the over-all 
processing objectives of the system must be 
kept in mind at all times. 
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The following are included in this section 
which presents techniques for the effective 
use of some DOS facilities: 

• Link Editing. Includes the linkage 
editor control statements and overlay 
structures, design and communication. 
In addition, examples illustrating 
module dependency and overlay tree 
structure are included. 

• Self-Relocating Program. Explains how 
to write a self-relocating program. It 
presents the rules, advantages, 
disadvantages, and techniques for 
writing self -relocating code. 

• Checkpoint/Restart. Includes the 
programmer's responsibilities when a 
checkpoint is taken during problem 
program execution. This also explains 
the CHKPT macro for checkpointing a 
program and describes checkpoint 
considerations for tape and disk, as 
well as for repositioning of files and 
restarting checkpoint ed programs. 



IBM 3211 Printer Support, 
error recovery techniques, 



Includes the 



Macro Writing. Includes the macro 
language and its effective use. Also 
included are examples illustrating how 
to write and use macros. 



Link Editing 



Link editing provides the user with the 
capability of combining separately 
assembled or compiled program sections or 
subprograms. To make this possible, the 
output of the language translators must be 
processed. At first, the separate program 
sections are in relocatable form; that is, 
the address constants are identified for 
later modification to absolute execution 
time values. The linkage editor (LNKEDT) 
links and relocates separate program 
sections into a single phase that can be 
loaded by the control program and then 
executed . 

Every relocatable program must be 
processed by the linkage editor before it 
can be executed. Once a program is edited, 
it can be executed immediately, cataloged 
as a permanent entry in the core image 
library, or both cataloged and executed 
immediately. When a program is cataloged 
in the core image library, the linkage 
editor is no longer required for that 
program, because it can be loaded directly 
from the resident pack by the system loader 



of the control program. On the other hand, 
if a program is edited and executed 
immediately without cataloging, the linkage 
editor is required again the next time the 
program is to be executed. Cataloging is a 
system design decision based on such 
factors as frequency of use and space 
available in the core image library. 

In a system having a minimum of 32K 
positions of main storage, batched-job 
foreground multiprogramming, and private 
core image library support, the linkage 
editor can execute in any partition. A 
private core image library must be assigned 
when executing the linkage editor in a 
foreground partition. When executing the 
linkage editor in the background partition, 
if a private core image library is not 
assigned, the default is to the system core 
image library. Without the two options 
specified the linkage editor can execute in 
the background partition only. 



SYSTEM FLOW 



Figure 3.1 shows the system flow for the 
linkage editor program. Before the linkage 
editor program is executed, job control 
must perform these functions: 

• Process the OPTION statement. OPTION 
LINK or CATAL turns on the control 
program switches which cause job 
control to open the SYSLNK file. 
Unless these switches are on, the 
linkage editor control statements are 
invalid. 

• Copy the linkage editor control 
statements onto SYSLNK. The linkage 
editor control statements are ACTION, 
PHASE, INCLUDE, and ENTRY. The ACTION, 
PBASE, and ENTRY statements are copied 
directly on SYSLNK. There are two 
forms of the INCLUDE statement. 
INCLUDE statements with no operand are 
not copied but cause the data (object 
module) on SYSIPT to be written until 
the end-of-data (/*) occurs. If the 
object module to be linkage edited is 
cataloged in the relocatable library, 
the INCLUDE statement must have the 
name of the module as an operand. The 
format of the INCLUDE statement is 
copied, but the module is not. 

• Write an ENTRY statement with a blank 
operand if the job stream does not 
already contain one. When the EXEC 
LNKEDT statement is encountered, an 
ENTRY statement is created to ensure 
termination of the link edit input. 
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System loader brings in job control . 

I 

Job control reads and interprets job control statements. 

\ 

Job control causes linkage editor (LE) control statements and 
relocatable object modules to be placed on SYSLNK; object 
modules may be either on SYSIPT or in the relocatable library. 

\ 

When job control reads EXEC LNKEDT, it causes the system 

loader to bring in the linkage editor program. 

I 

Using SYSLNK (input) and SYS001 (work file) the linkage 
editor develops executable program. 

If OPTION CATAL is specified, linkage editor output is placed 
permanently in the core image library (the core image directory 
is updated). If OPTION LINK is specified, linkage editor out- 
put is placed temporarily in the core image library (the core image 
directory is not updated), and the next linkage editor output over- 
lays the last temporarily placed linkage editor output. 

Note: If a private core image library is assigned, output is placed in 
the private library rather than in the system core image library 
on SYSRES. Output can be placed in the system core image 
library only when executing the linkage editor in the back- 
ground partition . 

\ 

If a program just link-edited is to be executed, the EXEC statement 

causes the system loader to fetch it from core image library and 
begin execution . 




@© 



Linkage editor 
statements 

Object modules 



© 




SYS001 



Work file 



Figure 3.1. Linkage Editor System Flow 
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• Inform the system loader to load the 
linkage editor program. The linkage 
editor program uses the data on SYSLNK 
as input. It handles the relocatable 
modules as directed by the PHASE and 
INCLUDE statements to develop 
executable program phases. Some of the 
linkage editor program functions are: 

1. Extracting the modules named in 
INCLUDE statements from the 
relocatable library. If, in 
extracting a module, another 
INCLUDE statement occurs, this 
module is also retrieved. The 
nesting of modules is possible up 
to a depth of five (a level of 
six) . 

2. Constructing composite 
dictionaries for ESD and RLD data, 
to resolve all linkages between 
different control sections. 

3. Relocating each control section as 
necessary within a phase. 

4. Assigning the entire phase to a 
contiguous area in main storage. 

5. Modifying all relocatable address 
constants to contain the relocated 
value of their symbols. 

6. Searching the relocatable library 
for a cataloged object module with 
the same name as each unresolved 
external reference. The automatic 
library lookup feature (AUTOLINK) 
is particularly useful for 
retrieving IOCS modules. It may 
be suppressed. 

7. Building the core image directory 
phase headers and cataloging to 
the core image library, if CATAL 
is specified. 

If a phase by the same name was 
cataloged previously, the old phase is 
deleted and the new one is cataloged. 
Deletion removes the item from the 
directory, but it does not release the 
space in the library until a condense 
function occurs. 

If a private core image library is 
assigned, the linkage editor output is 
placed in the private rather than the 
system core image library, permanently if 
OPTION CATAL is specified or temporarily if 
OPTION LINK is specified (see Figure 3.1, 
point 6) . In this case, the library need 
not be on SYSRES as shown in Figure 3.1. 
Output may be placed in the system core 
image library (either permanently or 
temporarily) only when executing the 
linkage editor in the background partition. 



SYMBOLIC UNITS REQUIRED 



The symbolic units required by the linkage 
editor are basically a subset of those 
needed by the language translators: 

SYSIPT Module input 

SYSLST Programmer messages and 
listings 

SYSLOG Operator messages 

SYSRDR Control statement input (via 
job control) 

SYSLNK Input to the linkage editor 

SYS001 Work file 

Note that SYSRDR and SYSIPT may contain 
input for the linkage editor. This input 
is written on SYSLNK by job control. 

If output from the linkage editor is to 
be placed in a private core image library, 
the following symbolic unit is required: 

SYSCLB the private core image library 
may be assigned anywhere in 
the job stream but must be 
before the // EXEC LNKEDT 
statement . 



LINKAGE EDITOR CONTROL STATEMENTS 



Position 1 must be blank on linkage editor 
control statements. Otherwise, they follow 
the same format as job control commands. 
Refer to DOS System Control and System 
Service listed in the Preface for a 
detailed explanation of the control 
statements . 



ACTION Statement 



CLEAR 
MAP 
NOMAP 
ACTION ) NOAUTO 
CANCEL 
BG 
Fl 
F2 

This statement specifies linkage editor 
options. It is not required, but if used, 
it must appear as the first linkage editor 
statement in the input stream. If multiple 
operands are required, they may be placed 
on separate ACTION statements or on one 
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ACTION statement separated by commas. The 
ACTION statement is effective only for the 
next linkage editor execution. The 
parameters have the following meanings: 



CLEAR 



MAP 



NOMAP 
NOAUTO 



CANCEL 



BG 
Fl 
F2 



Set the unused area of the core 
image library to binary zeros. 
The linkage editor clears from the 
next available entry (taken from 
the core image directory) to the 
end of the core image library. 
Because this is time-consuming, 
use it only if the areas defined 
by DS statements must be filled 
with zeros. 

Write main storage map and error 
diagnostics on SYSLST. Whenever 
SYSLST is assigned, MAP is 
automatic unless NOMAP is 
specified. 

Nullify MAP action. 

Suppress AUTOLINK function for the 
entire program, not just one 
phase . 

Cancel the job if the content of 
the linkage editor input is in 
error. See messages 21001 to 
21701 in the DOS Messages listed 
in the Preface . 

Causes the end of supervisor 
address used in linkage editor 
calculations to be set to the 
beginning of the partition 
specified, plus the length of the 
label area and of the save area. 
The end of supervisor address in 
the communications region is not 
changed. 

The BG, Fl and F2 operands 
provide the capability of link 
editing a program to execute in a 
partition other than that in which 
the link edit function is taking 
place. Programs that have a phase 
origin of S (or * for the first 
phase of a program) can be 
origined to the specified 
partition by use of the operands. 

Use of the ACTION BG statement 
is possible only in a system 
supporting the batched- job 
foreground and private core image 
library options when the linkage 
editor is executing in a 
foreground partition. 

Use of the ACTION Fl (or F2) 
statement in a multiprogramming 
environment requires that the 
partition be allocated. If these 



operands are used in a non-MPS 
environment, they are ignored. 

If none of these operands is 
present, the program will be link- 
edited to execute in the partition 
in which the link edit function is 
taking place, unless otherwise 
specified on the PHASE statement. 

An example of the use of the 
ACTION Fl statement follows. 
Assume a 64K machine with: 

8K supervisor 

24K background area 

16K foreground 2 area 

16K foreground 1 area. 

When executing the linkage 
editor in the background the 
statement PHASE PHASE1,S causes 
PHASE1 to be origined at 8K (the 
end of the supervisor area). The 
sequence 

ACTION Fl 

PHASE PHASE1,S 

causes PHASE1 to be origined at 
48K (the beginning of the 
foreground 1 area) plus the length 
of the foreground save area. 

When executing the linkage 
editor in foreground 2, the 
statement PHASE PHASE1,S causes 
PHASE1 to be origined at 32K (the 
beginning of the foreground 2 
area) plus the length of the 
foreground save area. The 
sequence 

ACTION BG 
PHASE PHASE1,S 

causes PHASE1 to be origined at 
the end of the supervisor area. 



PHASE Statement 



PHASE name , origin [ , NOAUTO 3 

A program phase is the section of a program 
that is loaded by the system loader as a 
single overlay with a single FETCH or LOAD. 
The input for building a single phase 
consists of the text from one or more 
complete control sections. Therefore, 
programs may consist of many phases, or a 
phase may consist of many subprograms or 
control sections. 



i 
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The PHASE statement provides the linkage 
editor with the phase name and an origin 
point for the phase. The phase name 
catalogs the phase in the core image 
library and retrieves it for execution. 
Job control uses the phase name to 
construct a single track phase directory 
before each job step is executed. This 
phase directory is built for all background 
program executions. If executing in the 
foreground, this phase directory is built 
under link, edit, and go conditions. The 
entries to this directory are taken from 
the core image directory for any phase 
where the first four characters of the name 
are identical to those in the name 
specified in the EXEC statement. The 
directory entry contains such information 
as loading address, entry point, and 
starting disk address in the core image 
library. The separate phase directory 
permits faster retrieval of the phases. 

The entries in the operand field 
represent the following: 

name Symbolic name of the phase, 

consisting of 1 to 8 alphameric 
characters. The first 4 
characters of a multiphase program 
should be the same to achieve 
maximum retrieval efficiency. 

origin Specification of the load address 
of the phase. The load address 
can be one of six forms: 



partition is allocated, 
ACTION Fl or F2 has the same 
effect as F+address. 



5. * [±relocation] . This is the 
most frequently used format 
and specifies an origin point 
for a phase at the next 
available core location. 



6. symbol [(phase)] 

[±relocation] . This format 
specifies an origin point for 
a phase at the same point as 
previously defined symbol 
(for overlays). 

A detailed explanation of the 
origin parameter is given in the 
DOS System Control and System 
Service listed in the Preface . 
Also refer to Link Editing 
Examples . 

NOAUTO Suppress the AUTOLINK function for 
this phase only. 



INCLUDE Statement 



INCLUDE tmodulename] [, (namelist) ] 



1. S [+relocation] . If link 
editing in the background, 
the origin point is at the 
end of the supervisor, the 
save areas, and the area 
assigned to the COMMON pool, 
if any. If link editing in 
the foreground, the beginning 
address of the partition is 
substituted for the end of 
supervisor address. 

2. ROOT. This phase is 
designated as the root phase, 
which remains in main storage 
throughout execution. Its 
location is the same as with 
format S. 

3. +displacement. The origin 
point is set at a specified 
location; +0 must be used for 
any self-relocating program. 

4. F+address. This format is 
used to begin the program at 
the start of a foreground 
partition when link editing 
in the background and the 
foreground partition is not 
allocated. If the foreground 



This statement specifies that an object 
module is to be included for editing by the 
linkage editor. The system assumes the 
location of the module as follows: 

1. Both operands missing. The object 
module is on SYSIPT; it is copied onto 
SYSLNK. 

2. Modulename given. The object module 
is cataloged in the relocatable 
library under the same name. 

3. Second operand only given. The object 
module is in the input stream on 
SYSLNK. The parameters represent the 
following: 

modulename Use this parameter only if the 
module is cataloged in the 
relocatable library. It 
consists of 1 to 8 alphameric 
characters and must be the same 
as the name used when the module 
was cataloged. 

(namelist) This parameter provides the 
ability to select particular 
control sections from a given 
module. It is expressed as 
Ccsnamel, csname2, ...). 
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ENTRY Statement 



ENTRY [entrypoint] 

The ENTRY statement signals the end of 
program input to the linkage editor. The 
entrypoint operand indicates the transfer 
address for the first phase as follows: 

1. If omitted, the first significant 
address in an END record encountered 
during the generation of the first 
phase is used; or, if no such operand 
is found, the load address of the 
first phase is used. 

2. If given, it must be the name of a 
CSECT or a label definition defined in 
the first phase. 

The ENTRY statement can be completely 
omitted because job control automatically 
writes an ENTRY statement with a blank 
operand when it encounters the EXEC LNKEDT 
statement . 



labeled tapes are processed. This same 
area is used by nonsequential DASD 
files with fewer extents, and by 
labeled tape files. 

The LBLTYP statement is not required if 
only unlabeled tape files and/or sequential 
DASD files are being processed. Only one 
LBLTYP statement is submitted. The 
placement of the statement in the job 
stream varies as shown: 

• Non-self-relocating 

(background/foreground) . Immediately 
preceding the EXEC LNKEDT statement at 
linkage editor time. 



Self -relocating 
(background/foreground) . 
EXEC for the program. 



Ahead of the 



Examples of various linkage editor 
functions follow. 



SUMMARY OF CONSIDERATIONS FOR LINK AND 
CATAL OPTIONS 



LBLTYP Job Control Statement 



// LBLTYP j TAPE 
NSD 



(TAPE (nn)l 
\NSD (nn) f 



The label storage records for standard 
labeled tape files and nonsequential DASD 
files (direct access, indexed sequential, 
or DTFPH with all packs mounted) are 
brought into the label save area of the 
partition containing the processing 
program. Therefore, main storage must be 
reserved by the user whenever such files 
are processed. Because this area is used 
during OPEN for one file at a time, the 
total area needed is that required by the 
largest file. 

Main storage reservation is accomplished 
by the LBLTYP statement. The amount of 
main storage reserved is governed by the 
operand TAPE or NSD as follows: 

• TAPE reserves 80 bytes of main storage. 
This format is used when standard 
labeled tape files and no nonsequential 
DASD files are processed, nn is 
ignored by job control. This same 
80-byte area is used by all labeled 
tape files. 

• NSD reserves 84 bytes plus 20 bytes per 
extent. The number of extents is 
specified in the nn parameter for the 
nonsequential file that has the largest 
number of extents. This format is used 
when nonsequential DASD files are 
processed, regardless of whether 



1. SYSLNK must be assigned, or LINK and 
CATAL options are ignored (switches 
are not set) . If executing the 
linkage editor in a foreground 
partition, a private core image 
library (SYSCLB) must be assigned. 
This is possible only in a system 
supporting the batched- job foreground 
and private core image library 
options . 

2. Unless the switches are set by the 
LINK or CATAL option, the linkage 
editor control statements are ignored. 

3. The CATAL option sets the LINK and 
CATAL switches. 

4. When the LINK switches are set, the 
output of the language translators is 
placed on SYSLNK. 

5. LINK and CATAL switches are turned off 
by: 

a. /6 or JOB statement 

b. An error during compilation. 

6. Completion of cataloging (update of 
transient, library routine, and 
foreground program directories, and 
system status report) occurs when the 
/S statement is read by job control. 

7. If a successful link edit has not 
occurred, cataloging does not take 
place. 
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If multiple linkage editor job steps 
are set up as one job, keep these 
points in mind: 

a. It is not possible to CATAL into 
the core image library with 

// OPTION CATAL and then have 
another linkage editor job step 
with // OPTION LINK in the same 
job. Operator message ISInD 
(STATEMENT OUT OF SEQUENCE) 
results. 

b. If a compilation is being 
performed, the link switches may 
be turned off by an error. When 
cataloging to the core image 
library, therefore, it is 
advisable to handle multiple job 
steps as separate jobs (each with 
/£) to be sure that the cataloging 
operation is finished on the /&. 

c. SYSLNK extents are reset each time 
before Job Control writes a new 
series of link edit control 
statements onto SYSLNK. Core 
image library directory and 
subdirectory are updated at /S if 
the CATAL option is included. 



Overlay Tree Structure 



To place a program in an overlay structure, 
the programmer should be familiar with the 
following terms: 

Phase : A phase is the smallest functional 
unit (one or more control sections) that 
can be loaded as one logical entity during 
the execution of the program. A phase can 
contain up to 524,288 bytes of text. The 
root phase (first phase) remains in main 
storage throughout execution. 

Tree : A tree is the graphic representation 
that shows how phases can use main storage 
at different times. It does not imply the 
order of execution, although the root phase 
is the first to receive control. 

The design of an overlay program 
requires the organization of the control 
sections of the program in an overlay tree 
structure. The tree structure is developed 
considering: 

1. The amount of available main storage. 

2. The frequency of use of each control 
section. 



LINKAGE EDITOR PROGRAM CONSIDERATIONS 



The linkage editor program consists of 
eight phases. The efficiency of link 
editing programs into the core image 
library depends upon the amount of main 
storage allocated to the partition where 
the linkage editor is executing. If a 
minimum of 14K of main storage is available 
several phases of the linkage editor 
program are contained within main storage 
during linkage editor processing. If less 
than 14K is available, only one linkage 
editor processing phase may be resident in 
the partition at one time. Some time is 
lost fetching the additional phases as they 
are needed. 



PROGRAM OVERLAY STRUCTURES 



Overlay is a programming technique that 
minimizes the main storage requirements of 
a program. To use overlay, the programmer 
should be familiar with two related 
techniques : 

1. Organizing the program as an overlay 
structure . 

2. Communicating with the control program 
during execution through FETCH and 
LOAD macros. 



3. The dependencies between control 
sections . 

4. The manner in which control should 
pass within a path, from one path to 
another, and from one region to 
another. 

When the overlay tree structure for a 
program is determined, PHASE statements are 
prepared which segment the program in that 
manner. 



Overlay Tree Design 



To begin constructing an overlay tree, the 
programmer should select those modules that 
receive control at the beginning of 
execution plus those that should always 
remain in main storage; these form the root 
phase. The rest of the tree can be 
developed by determining the dependency of 
the remaining phases and how they can use 
the same main storage locations at 
different times during execution. 

Module dependency is determined by the 
requirements of a control section or module 
for a given routine in another control 
section. A module depends upon a control 
section to which it branches or whose data 
it must process. The required control 
section must be in main storage before 
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execution can continue beyond a given point 
in the program. Figure 3.2 illustrates how 
modules depend on each other, and the paths 
that result from these dependencies. 

The module containing control sections A 
and B can be used to form the root phase. 
The module containing control sections C 
and D can use the same main storage as the 
module containing control sections J and K. 
Phases that use the same main storage area 
can overlay each other during execution. 
The module containing control section E can 
use the same main storage as the module 
containing control sections F and G. The 
module containing control section H can use 
the same main storage as the module 
containing control section I. The module 
containing control section L can use the 
same main storage as the module containing 
control sections M and N. 
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Note: A through N are Control Sections. 



Figure 3.2. Module Dependency 



Figure 3.3 shows the resulting overlay 
tree structure. The longest path in this 
structure is formed by phases 1, 2, 4, and 
5, because the program requires 21,000 
bytes when they are in main storage. Thus, 
the minimum main storage requirement for 
the program is 21,000 bytes. The program 
would require 46,000 bytes if not put in an 
overlay structure. The linkage editor 
assigns the relocatable origin of the root 
phase (the origin of the program) at 0. 
The relative origin of each phase is 



determined by 0, plus the length of all 
phases in the path. For example, the 
origin of phases 3 and 4 is equal to + 
5,000 (the length of phase 2) + 6,000 (the 
length of the root phase) . 
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Figure 3.3. overlay Tree Structure 



When a phase is in main storage, all 
phases in its path are in main storage. 
(Each time a phase is loaded, all phases in 
its path are also loaded if they are not 
already in main storage.) In Figure 3.3, 
when phase 4 is in main storage, phases 1 
and 2 are also in main storage. This does 
not imply that phase 5 or 6 is in main 
storage because neither phase is in the 
path of segment 4. 

The position of the phases in an overlay 
tree structure does not necessarily imply 
the order in which they are executed. A 
phase can be loaded and overlaid as many 
times as required by the logic of the 
program. If a phase is modified during 
execution, that modification remains only 
until the phase is overlaid. However, a 
phase cannot be overlaid by itself. 

Phases that can be in main storage 
simultaneously are considered to be 
inclusive. Phases not in the same path are 
considered to be exclusive; they cannot be 
in main storage simultaneously. 

Phases on which two or more exclusive 
phases are dependent are called common 
phases. A phase common to two other phases 
is part of each. In Figure 3.3, phase 7 is 
common to phases 8 and 9, but not to phase 
2. 



148 DOS System Programmer's Guide 



Overlay Communication 



The programmer must know how his program 
can communicate with the control program 
during execution. Two ways in which he can 
overlay phases in his program are: 

1. By a LOAD macro instruction, that 
loads the named phase into main 
storage and returns control to the 
calling phase. 

2. By a FETCH macro instruction, that 
loads the specified phase into main 
storage and passes control to the 
entry address of the fetched phase. 

Some of the advantages are: 

1. The LOAD macro allows the programmer 
to load his phases in violation of the 
tree structure that was defined at 
linkage editor time. 

2. The LOAD macro allows the programmer 
to load phases from other programs. 

However, these responsibilities are 
associated with the use of these macros: 

1. The programmer must keep track of 
which phases are in main storage. 

2. The programmer must be aware of 
overlay structure and he must know the 
phase names at compilation or assembly 
time . 

A phase that is loaded into main storage 
by the FETCH macro is always relocated 
unless the self-relocating option was 
specified at linkage editor time. A phase 
that is loaded into main storage by the 
LOAD macro is relocated relative to the 
same structure as when it was linkage 
edited; i.e., LOADs can be made outside the 
defined tree, but it is not possible for 
the system to ensure that references 
outside the tree will be valid. 



Self-Relocating Programs 



A system supporting multiprogramming has 
the capability of executing self-relocating 
programs. A self -relocating program is one 
that can be executed at any location in 
main storage. Writing a self-relocating 
program is an efficient coding technique 
because self-relocating programs are 
link edited only once for execution in 
any partition. When linkage editing, use 
OPTION CATAL and a PHASE card such as: 



This causes the linkage editor to assume 
that the program is loaded at core location 
zero, and to compute all absolute addresses 
from the beginning of the phase. The job 
control EXEC function recognizes a zero 
phase address and adjusts the origin 
address to compensate for the current 
partition boundary save area and label area 
(if any) . It then gives control to the 
updated entry address of the phase. 



RULES FOR WRITING SELF-RELOCATING PROGRAMS 



In general, if a problem program is written 
to be self-relocating, the following rules 
must be adhered to: 

1. The supervisor must support 
multiprogramming (that is, MPS=YES or 
BJF must be specified as a parameter 
in the SUPVR macro at system 
generation time) . 

2. The PHASE card must specify an origin 
of +0. 

3. The program must relocate all address 
constants used in the program. 
Whenever possible, use the LA 
instruction to load an address in a 
register instead of using an A-type 
address constant. For example. 



Instead of using : 



USING 


*,12 


BALR 


12,0 


LA 


12,0(12) 


BCTR 


12,0 


BCTR 


12,0 


LA 


l,EOF 


ST 


l,AEOF 



EOF 



EOJ 



AEOF DC 



Use: 



USING 

BALR 

LA 

BCTR 

BCTR 

• 

LA 



10, AEOF 



A (EOF) 



*,12 

12,0 

12,0(12) 

12,0 

12,0 



10, EOF 



PHASE Phasename,+0 



EOF 



EOJ 
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4. If logical IOCS is used, the program 
must use the OPENR and CLOSER macros 
to open and close files. 

5. If physical IOCS is used, the program 
must relocate all CCW address fields. 

6. Register notation must be used when 
issuing an imperative macro (I/O, I/O 
control, and supervisor 
communication) . Register notation 
utilizes less main storage and permits 
faster execution. 



9. The calling program is responsible for 
relocating all address constants in 
the calling list(s). See Figure 3.4 
for an example of calling program 
relocating the address constants in a 
calling list. 



ADVANTAGES OF SELF-RELOCATING PROGRAMS 



The following rules apply to multimodule 
programs . 

7. The relocation factor should be 

calculated and stored in a register 
for future use. For register economy, 
the base register can hold the 
relocation factor. 



For 


example 


5 






USING 


*,12 




BALR 


12, 


,0 




LA 


12, 


,0(12) 




BCTR 


12, 


r0 




BCTR 


12, 


r0 



Register 12 now contains the 
relocation factor and the program 
base. 



Self- relocating programs have the ability 
to run in any one of the three problem 
program partitions without needing linkage 
editing again. The program can also be 
loaded anywhere within a partition. The 
restriction of specific partition 
allocations need not be adhered to with a 
self-relocating program because it 
relocates itself. 



DISADVANTAGES OF SELF-RELOCATING PROGRAMS 



Self -relocating programs are slightly more 
time consuming to write and they usually 
require slightly more main storage. 



When branching to an external address, 
use one of the following techniques: 



a. 



L 1 5 , =V ( EXTERNAL) 
BAL 14,0(12,15) 



L 15 , =V (EXTERNAL) 
AR 15,12 
BALR 14 , 15 



where register 12 is the base register 
containing the relocation factor. 



PROGRAMMING TECHNIQUES 



A self-relocating program is capable of 
proper execution, regardless of where it is 
loaded. DTFDI should be used to resolve 
device differences between partitions. A 
self-relocating program must also adjust 
all of its own absolute addresses to point 
to the proper address. This must be done 
after the program is loaded, and before the 
absolute addresses are used. 
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// JOB A 

// OPTION LINK 

// EXEC ASSEMBLY 

CSECT1 START 

USING * r 12 
BALR 12,0 
LA 12,0(12) 
BCTR 12,0 
BCTR 12,0 



Use load point value as the base to 
find the load point value. 



Modify the CALL address constant list. 



LA 1,A 
LA 2,B 
LA 3,C 
LA 4,D 
STM 1,4, LIST 
LA 13,SAVEAREA 
L 15 , =V (EXTERNAL) 

AR 15,12 Adjust CALL address by relocation 
factor. 

(15),(A,B,C,D) 

*-16 For address constants (4 bytes each). 



CALL 
LIST EQU 

EOJ 
SAVEAREA DC 9D , I 

END 
/* * 

// EXEC ASSEMBLY 
CSECT2 START 

ENTRY EXTERNAL 
EXTERNAL SAVE (14,12) 

USING *,12 

BALR 12,0 



RETURN (14, 12) 

END 
/* * 
// EXEC LNKEDT 



Establish new base 



Figure 3.4. Relocating Address Constants in a Calling List 



Within these self-relocating programs, 
some macros generate self -relocating code. 
For example, the MPS utility macros are 
self -relocating (that is, they modify all 
of their own address constants to their 
proper values before using them) . OPENR 
and CLOSER macros are designed to be used 
in self -relocating programs. OPENR and 
CLOSER can be used in place of OPEN and 
CLOSE, and adjust all of the address 
constants in the DTFs opened and closed. 
OPENR and CLOSER can be used in any program 
because the OPENR macro computes the amount 
of relocation. If relocation is 0, the 
standard open is executed. In addition, 
all of the module generation (xxMOD) macros 
are self -relocating. 

The addresses of all address constants 
containing relocatable values are listed in 
the relocation dictionary in the assembly 
listing. This dictionary includes both 
those address constants that are modified 
by self-relocating macros, and those that 



are not. The address constants not 
modified by self-relocating macros must be 
modified by some other technique. After 
the program has been linkage edited with a 
phase origin of +0, the contents of each 
address constant is the displacement from 
the beginning of the phase to the address 
pointed to by that address constant. 

The following techniques place relocated 
absolute addresses in address constants. 
These techniques are required only when the 
LA instruction cannot be used. 

Technique 1 

Named A-type address constants: 



ADCON 



LA 
ST 



DC 



4,ADCONAME 
4, ADCON 



A(ADCONAME) 
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Technique 2 

A-type address constants in the literal 
pool: 



LA 


3 f =A(ADCONAME) 


LA 


4,ADCONAME 


ST 

• 


4,0(3) 


• 
LTORG 






=A(ADCONAME) 


Technique 3 





B. If CCW list is static during program 
execution : 



LA 4 , IOAREA 
ST 4, TAPECCW 
MVI TAPECCW, 1 



TAPECCW CCW 1, IOAREA, X* 20* ,100 



A-type address constants with a specified 
length of three bytes, and a nonzero value 
in the adjacent left byte (as in CCWs) : 



DS 



Technique 4 



CL100 



A. 



If CCW list dynamically changes during 
program execution: 



IC 


3, TAPECCW 


LA 


4, IOAREA 


ST 


4, TAPECCW 


STC 


3, TAPECCW 



TAPECCW CCW 1, IOAREA, X* 20', 100 



Named V-type or A-type address constants: 



LA 3,ADCONAST Determine 
S 3,ADCONAST Relocation 
factor 



L 4,ADCON 

AR 4,3 Add Relocation factor 

ST 4,ADCON 



IOAREA 



DS 



CL100 



ADCONAST DC 
ADCON DC 



A(*) 

V(NAME) 



2. 



USING 


*,12 


BALR 


12,0 


LA 


12,0(12) 


BCTR 


12,0 


BCTR 


12,0 Reg. 12 contains re- 




location factor 


L 


11, TAPECCW 


ALR 


11,12 


ST 


11, TAPECCW 



TAPECCW CCW 1, IOAREA, X' 20* ,100 



IOAREA 



DS 



CL100 



Note that the load point of the phase is 
not synonymous with the relocation factor 
as developed in register 3 (technique 4). 
If the load point of the phase is taken 
from register (or calculated by a BALR 
and subtracting 2) immediately after the 
phase is loaded, it may be added to address 
constants with varying results. If the 
phase was linkage edited with an origin of 
+0, the correct results are obtained. If 
the phase was linkage edited with an origin 
of * or S, incorrect results are obtained 
because, both the linkage editor and the 
program itself have added the load point to 
all address constants. See Figure 3.5 for 
an example of a self -re locating program. 
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SOURCE 


STATEMENTS 
REPRO 








PHASE EXAMPLE, +0 




+0 ORIGIN IMPLIES SELF-RELOCATION 




PRINT NOGEN 






PROGRAM 


START 








BALR 


12,0 








USING ", 12 






x ROUTINE TO RELOCATE ADDRESS 


CONSTANTS 






LA 


1, PRINTCCW 




RELOCATE CCW ADDRESS 




ST 


l,PRINTCCB+8 




IN CCB FOR PRINTER 




LA 


1, TAPECCW 




RELOCATE CCW ADDRESS 




ST 


l,TAPECCB+8 




IN CCB FOR INPUT TAPE 




IC 


2, PRINTCCW 




SAVE PRINT CCW OP CODE 




LA 


1, OUTAREA 




RELOCATE OUTPUT AREA ADDRESS 




ST 


1, PRINTCCW 




IN PRINTER CCW 




STC 


2, PRINTCCW 




RESTORE PRINT CCW OP CODE 




LA 


1, INAREA 




RELOCATE INPUT AREA ADDRESS 




ST 


1, TAPECCW 




IN TAPE CCW 




MVI 


TAPECCW, READ 




SET TAPE CCW OP CODE TO READ 


- MAIN ROUTINE. . .READ TAPE AND 


PRINT RECORDS 


READTAPE 


LA 


1, TAPECCB 




GET CCB ADDRESS 




EXCP 


(1) 




READ ONE RECORD FROM TAPE 




WAIT 


(1) 




WAIT FOR I/O COMPLETION 




LA 


10, EOFTAPE 




GET ADDRESS OF TAPE EOF ROUTINE 




BAL 


Ik, CHECK 




GO TO UNIT EXCEPTION SUBROUTINE 




MVC 


OUTAREAC10), INAREA 




EDIT RECORD 




MVC 


OUTAREA+15C70), INAREA+10 


IN 




MVC 


OUTAREA+90C20), INAREA+80 


OUTPUT AREA 




LA 


1, PRINTCCB 




GET CCB ADDRESS 




EXCP 


(1) 




PRINT EDITED RECORD 




WAIT 


(1) 




WAIT FOR I/O COMPLETION 




LA 


10,CHA12 




GET ADDRESS OF CHAN 12 ROUTINE 




BAL 


Ik, CHECK 




GO TO UNIT EXCEPTION SUBROUTINE 




B 


READTAPE 






CHECK 


TM 


4(0,1 




CHECK FOR UNIT EXEC. IN CCB 




BCR 


1,10 




YES-GO TO PROPER ROUTINE 




BR 


Ik 




NO-RETURN TO MAINLINE 


CHA12 


MVI 


PRINTCCW, SKIPTOl 




SET SEEK TO CHAN 1 OP CODE 




EXCP 


(1) 




SEEK TO CHAN 1 IMMEDIATELY 




WAIT 


(1) 




WAIT FOR I/O COMPLETION 




MVI 


PRINTCCW, PRINT 




SET PRINTER OP CODE TO WRITE 




BR 


Ik 




RETURN TO MAINLINE 


EOFTAPE 


EOJ 






END OF JOB 




CNOP 


0,k 




ALIGN CCB'S TO FULL WORD 


PRINTCCB 


CCB 


SYS004, PRINTCCW, X' 


0<+00' 




TAPECCB 


CCB 


SYS001, TAPECCW 






PRINTCCW 


CCW 


PRINT, OUTAREA, SLI, 


L'OUTAREA 




TAPECCW 


CCW 


READ, INAREA, SLI, L* 


INAREA 




OUTAREA 


DC 


CL110' ' 






INAREA 


DC 


CL100' ' 






SLI 


EQU 


X'20' 






READ 


EQU 


2 






PRINT 


EQU 


9 






SKIPTOl 


EQU 
END 


X'8B» 
PROGRAM 







Figure 3.5. Self -Relocating Sample Program 



) 
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Linkage Editor Examples 



LINK EDIT- AND- EXECUTE-EXAMPLE 



1. 
2. 
3. 



// JOB LINKEXEC 

* LINK EDIT AND EXECUTE IN BACKGROUND, SINGLE PHASE, SINGLE OBJECT MODULE 

* RELOCATABLE MODULE NOT CATALOGED, BACKGROUND PROGRAM 

* NONSEQUENTIAL DASD € LABELED TAPE FILES TO BE PROCESSED 
// ASSGN SYSLNKjX 1 !^* 

// OPTION LINK 
PHASE PROGA,* 
INCLUDE 



H. 



Relocatable object deck 



/* 

5. // LBLTYP NSD(2) 

6. // EXEC LNKEDT 



7. Any job statements required for execution such as ASSGN or label statements. 

8 . // EXEC 

Data input as required. 



/* 
/& 

* 1. 

* 2. 

* 

* 3. 

* 



TO CATALOG AND EXECUTE, CHANGE STATEMENT 2 TO // OPTION CATAL. 
TO CATALOG ONLY, CHANGE STATEMENT 2 TO // OPTION CATAL AND 
REMOVE ALL STATEMENTS FOLLOWING LNKEDT EXCEPT /S 
TO USE MODULE FROM RELOCATABLE LIBRARY, CHANGE STATEMENT 3 
TO INCLUDE MODULES AND REMOVE ALL STATEMENTS UP TO // LBLTYP. 



Explanation for Link Edit and Execute 



This example illustrates the basic concept 
of linkage editing and executing by using a 
single phase that is constructed from a 
single relocatable object deck contained in 
punched cards. The program is executed in 
the background partition. Labeled tape and 
nonsequential DASD files are to be 
processed when the phase is executed. No 
more than two extents are used by any DASD 
file. 

Statement 1 : No assignments are necessary, 
because the system units required for 
linkage editing are in the assumed 
configuration. However, an ASSGN for 
SYSLNK is included to illustrate its 
position relative to the OPTION statement 
in case assignment is required. 

Statement 2 ; The OPTION LINK statement 
sets switches to indicate that a linkage 
editor operation is to be performed. If 
SYSLNK has not been assigned, the statement 
is ignored. Linkage editor control 
statements are not accepted unless the 



OPTION statement is processed. Because 
option is LINK, not CATAL, only link 
editing is performed; cataloging to the 
core image library does not occur. 

Statement 3 ; The PHASE statement is copied 
on SYSLNK, because position 1 is blank and 
the LINK switch is on. The operands are 
not examined until SYSLNK becomes input to 
the linkage editor program. 

When the PHASE statement is processed by 
the linkage editor, only one phase is 
constructed, because only one PHASE 
statement is submitted for the entire 
LNKEDT. The name of this phase is PROGA, 
as specified in the first operand. The 
second operand indicates the origin point 
for the phase. Because an * has been used, 
the phase begins in the next main storage 
location available, with forced doubleword 
alignment. Because this is the first and 
only phase, it is located at the end of the 
supervisor plus length of the label save 
area (reserved by LBLTYP) plus length of 
any area assigned to the COMMON pool (as 
designated by a CM entry in the relocatable 
module) . 



< 
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A relocation factor, either plus or 
minus, is used with the *, such as *+1024. 
This causes the origin point of the phase 
to be set relative to the * by the amount 
of the relocation term. This term can be 
expressed as: 

X'hhhhhh' — 1 to 6 hexadecimal digits 
dddddddd — 1 to 8 decimal digits 
nK — where K = 10 2 4 

*+1024 uses the second format and adds 1024 
bytes to the origin location. +1K or 
+X , 400 f gives the same result as +1024. 

Statement 4 : The INCLUDE statement has no 
operands, so the system reads the records 
from SYSIPT and writes them on SYSLNK until 
SYSIPT has an end-of-data (/*) record. The 
data on SYSIPT is expected to be the object 
module in card image format that is used in 
this linkage editor operation. If the 
output of the language translator (SYSPCH) 
is placed on 2311/2314/2319 instead of 
cards, it cannot be used directly as SYSIPT 
in a linkage editor operation because the 
records contain a stacker select code in 
position 1. SYSPCH must be converted to an 
80- position card image record. 

Statement 5 ; The LBLTYP statement causes a 
computation of the number of bytes that are 
required for label storage data in the 
program to be linkage edited. In this 
example, 124 bytes are reserved (84 + 
[2x20]). The calculation is saved by job 
control and passed on first to the linkage 
editor and later to LIOCS. 

Statement 6 ; The EXEC LNKEDT writes an 
ENTRY statement with no operand on SYSLNK 
and causes the system loader to bring in 
the linkage editor program. 

Using the data just placed on SYSLNK as 
input, the linkage editor develops 
executable code. The output is placed in 
the next available space of the core image 
library (immediately after the last 
cataloged phase) . This is true regardless 
of whether the program is cataloged or not. 
Cataloging causes the updating of the 
directory to reflect a new ending point for 
the library. If cataloging does not occur, 
the next program that is linkage edited 
overlays it. For this reason, a linkage 
edited program that is not cataloged is 
said to be placed in the temporary area of 
the core image library. Also, a program 
that is linkage edited without cataloging 



must be linkage edited whenever it is used. 
No ACTION options are specified. 
Therefore, in resolving the external 
references, the system makes use of the 
AUTOLINK feature. Error diagnostics and a 
main storage map are written on SYSLST, 
because SYSLST is assigned. 



Statement 7 ; Because the program is not 
cataloged, it must be executed immediately. 
Any pertinent job control statements are 
entered at this point. 

Statement 8 : An EXEC statement with no 
operand indicates that the phase to be 
executed was just linkage edited. 
Therefore, no search of the core image 
directory is required, and the system 
loader brings the program into main storage 
from the temporary area and transfers 
control to its entry point. In this 
example, the entry point is either the 
address specified in the END record, or the 
phase load address if the END address is 
omitted, because the automatic ENTRY 
statement is in effect. 

This example can be modified to 
illustrate the following: 

1. Catalog and execute . To cause this 
phase to be cataloged rather than 
merely linkage edited, change the 
OPTION (statement 2) from LINK to 
CATAL. The core image library 
directory still refers to the old 
version of the program. It is not 
updated until /& has been read. 

2. Catalog only . To catalog only, change 
the OPTION (statement 2) from LINK to 
CATAL and remove all data following 
the EXEC LNKEDT (statement 6) up to 
the /£ statement. 

3. Catalog object module in relocatable 
library . The name to catalog the 
object module into the relocatable 
library must be added to the INCLUDE 
statement. If the name is RELOCA, the 
statement becomes INCLUDE RELOCA. The 
relocatable object deck and /* 
statement are removed. This form of 
the INCLUDE statement is written on 
SYSLNK when it is read by job control. 
The linkage editor retrieves the 
object module when it encounters the 
INCLUDE statement because it uses 
SYSLNK for input. 
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CATALOG TO CORE IMAGE LIBRARY EXAMPLE 



// JOB CATALCIL 

* LINK EDIT AND CATALOG TO CORE IMAGE LIBRARY 

* SINGLE PHASE, MULTIPLE OBJECT MODULES, FOREGROUND PROGRAM 

* MIXTURE OF CATALOGED AND UNCATALOGED RELOCATABLE MODULES 

* LABELED TAPE FILES AND SEQUENTIAL DASD FILES TO BE PROCESSED 

1. // ASSGN SYSLNK,X , 190 , 

2. // OPTION CATAL 

3. PHASE PROGB,F+32768 

4. INCLUDE 



/* 



Relocatable object deck 



INCLUDE SU3RX 
INCLUDE SUBRY 
INCLUDE 

Relocatable object deck 



/* 



5. // LBLTYP TAPE 

6. // EXEC LNKEDT 

7. /g 



Explanation for Catalog to Core Image 
Library 



This example illustrates the cataloging of 
a single phase composed of multiple 
relocatable object modules. These modules 
are located in the input stream and in the 
relocatable library. Labeled tape files 
and sequential DASD files are processed 
when the phase is executed. The program is 
executed in a foreground partition. Assume 
that the foreground partition begins at 
location 32768. 



phase, F plus the location address in the 
foreground partition must be specified. 

A program may be linkage edited to any 
address that *f alls within a foreground 
partition. The load address does not have 
to coincide with the partition address. 
However, the program must be of such a size 
that it can reside in the available core 
defined from the load address to the end of 
the partition. 

The address may be expressed in one of 
three forms: 



Statement 1 : The SYSLNK assignment 
indicates the relationship to the OPTION 
statement, although it is not required 
because of the assumed configuration. 

Statement 2 i The OPTION CATAL statement 
sets the LINK switches, as well as a CATAL 
switch. If SYSLNK is not assigned, the 
statement is ignored. The linkage editor 
control statements are not accepted unless 
the OPTION statement is processed. Linkage 
editing and cataloging to the core image 
library will occur. 



Statement 3: 



Only one PHASE is 

It is cataloged to the core 



constructed. 

image library and retrieved by the name 

PROGB. Because this is to be a foreground 



X*hhhhhh' — A hexadecimal number of H 

to 6 digits 
dddddddd — A decimal number of 5 to 

8 digits 
nnnnK — Where K = 1024 and n is 2 

to 4 digits 

+X , 8000*, +32768, and +32K are equivalent. 
The actual origin point of the phase is 
adjusted upward from the address 
specification to allow for the partition 
save area, and the label information 
(LBLTYP statement reservation). 

Statement 4 : Four modules make up this 
phase. The first and last are not 
cataloged in the relocatable library; 
therefore the object decks must be on 
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SYSIPT, and each must be followed by the 
end-of-data record (/*). SUBRX and SUBRY 
are cataloged previously to the relocatable 
library by those names. Job control puts 
the uncataloged modules on SYSLNK in place 
of their INCLUDE statements. Job control 
copies the INCLUDE statements for the 
cataloged modules. 

Statement 5 : The LBLTYP statement has the 
operand TAPE, rather than NSD because 
labeled tapes and sequential DASD files are 
processed when the phase is executed. 
Eighty bytes are reserved ahead of the 
actual phase for label information. LBLTYP 
NSD is also satisfactory because it 
generates a minimum of 104 bytes and tapes 
require only 80. 

Statement 6 : The EXEC LNKEDT statement 
causes the system loader to bring in the 
linkage editor program. SYSLNK now becomes 
input to the linkage editor. It contains 
the following: 

PHASE PROGB,F+32768 

First uncataloged relocatable deck 

INCLUDE SUBRX 

INCLUDE SUBRY 

Second uncataloged relocatable deck 

ENTRY 

The modules are linkage edited so that they 
occupy contiguous areas in main storage in 
the sequence in which they appear in the 
input stream. When the linkage editing is 
completed, cataloging to the core image 
library occurs because of the CATAL option. 
The core image directory is checked to make 
sure the new phase entries fit. If not, 
the job is canceled. The directory is 
scanned for any match to a phase being 



cataloged. A match is deleted from the 
directory. The system directory is updated 
to reflect the changes. Job control is 
brought into main storage. 



Statement 7 : Because CATAL was specified, 
a special routine is executed when the /& 
control statement is read by job control. 
This routine updates the transient, 
library-routine, and foreground- program 
directories. A system status report is 
printed to reflect the usage and available 
space in each of the libraries and 
directories. These operations do not occur 
in a LINK situation. The /£ resets the 
CATAL option, that is, it turns off the 
LINK and CATAL switches. 

The example can be modified to 
illustrate a catalog-and-execute operation 
by inserting the following data between the 
EXEC LNKEDT and /S statements: 

1. Any job control statements required 
for execution or PROGB 

2. A // EXEC statement 

3. Any card reader input for PROGB 

Note that the actual update of the 
directories and the system status report 
are delayed until completion of the 
execution of PROGB, when /S is read. From 
a system design standpoint this is not 
desirable because of possible operational 
problems. Making the execution of PROGB a 
separate job avoids any difficulties. All 
core image library directories are updated 
at /&. This is time consuming and should 
not be done for each module cataloged. 
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EXECUTE LINKAGE EDITOR IN FOREGROUND AND CATALOG TO PRIVATE CORE IMAGE LIBRARY EXAMPLE 

// JOB CATLCIL 

* LINK EDIT AND CATALOG TO PRIVATE CORE IMAGE LIBRARY 

* LINKAGE EDITOR EXECUTING IN FOREGROUND 

* SINGLE PHASE, MULTIPLE OBJECT MODULES, FOREGROUND PROGRAM 

* MIXTURE OF CATALOGED AND UNCATALOGED RELOCATABLE MODULES 

* LABELED TAPE FILES AND SEQUENTIAL DASD FILES TO BE PROCESSED 

1. ASSGN SYSCLB, X* 191* 

2. // ASSGN SYSLNK, X» 190* 

3. // OPTION CATAL 

4. PHASE PROGB,S 

5 . INCLUDE 



/* 



Relocatable object deck 



INCLUDE SUBRX 
INCLUDE SUBRY 
INCLUDE 

Relocatable object deck 



6. // LBLTYP TAPE 

7. // EXEC LNKEDT 

8. /€ 



Explanation for Catalog to Private Core 
Image Library 



This example- illustrates the execution of 
the linkage editor in a foreground 
partition and the cataloging of a phase to 
a private core image library. This 
function is possible only in a system 
supporting the batched- job foreground and 
private core image library options. The 
phase being cataloged is the same as that 
in the previous example where the link edit 
was executed in the background. 

Statement 1 ; The assignment of a private 
library is accomplished by the ASSGN SYSCLB 
statement. The label for SYSCLB must be 
stored on PARSTD or STDLABEL cylinder, or, 
if the DL3L statement is included in the 
job stream, it must follow the ASSGN SYSCLB 
statement. 

Statement 2 ; The SYSLNK assignment 
indicates the relationship to the OPTION 
statement, although it is not required 
because of the assumed configuration. 

statement 3 : The OPTION CATAL statement 
sets the LINK switches, as well as a CATAL 
switch. If SYSLNK is not assigned, the 
statement is ignored. The linkage editor 
control statements are not accepted unless 



the OPTION statement is processed. Linkage 
editing and cataloging to the core image 
library will occur. 



Only one PHASE is 

It is cataloged to the 



Statement 4 : 
constructed, 
private core image library and retrieved by 
the name PROGB, An origin point of S 
origins PROGB at the starting address of 
the foreground partition, plus the length 
of the save areas and the area assigned to 
the COMMON pool, if any. 

Statement 5 : Four modules make up this 
phase. The first and last are not 
cataloged in the relocatable library; 
therefore, the object decks must be on 
SYSIPT, and each must be followed by the 
end-of-data record (/*). SUBRX and SUBRY 
are cataloged previously to the relocatable 
library by those names. Job control puts 
the uncataloged modules on SYSLNK in place 
of their INCLUDE statements. Job control 
copies the INCLUDE statements for the 
cataloged modules. 

Statement 6 ; The LBLTYP statement has the 
operand TAPE, rather than NSD because 
labeled tapes and sequential DASD files are 
processed when the phase is executed. 
Eighty bytes are reserved ahead of actual 
phase for label information. LBLTYP NSD is 
also satisfactory because it generates a 
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minimum of 104 bytes and tapes require only 
80. 

Statement 7 ; The EXEC LNKEDT statement 
causes the system loader to bring in the 
linkage editor program. SYSLNK now becomes 
input to the linkage editor. It contains 
the following: 

PHASE PROGB, S 

First uncataloged relocatable deck 

INCLUDE SUBRX 

Second uncataloged relocatable deck 

The modules are link- edited so that they 
occupy contiguous areas in main storage in 
the sequence in which they appear in the 
input stream. When the linkage editing is 
completed, cataloging to the private core 
image library occurs because of the CATAL 
option. The private core image directory 
is checked to make sure the new phase 
entries fit. If not, the job is canceled. 
The directory is scanned for any match to a 
phase being cataloged. A match is deleted 
from the directory. The system directory 
is updated to reflect the changes. Job 
control is brought into main storage. 

Statement 8 ; Because CATAL was specified, 
a special routine is executed when the /& 
control statement is read by job control. 
This routine updates the transient. 



library- routine, and foreground-program 
directories for the private core image 
library. A system status report is printed 
to reflect the usage and available space in 
each of the libraries and directories. 
These operations do not occur in a LINK 
situation. The /S resets the CATAL option, 
that is, it turns off the LINK and CATAL 
switches . 

The example can be modified to 
illustrate a catalog- and-execute operation 
by inserting the following data between the 
EXEC LNKEDT and /& statements: 

1. Any job control statements required 
for execution or PROGB 

2. A // EXEC statement 

3. Any card reader input for PROGB 

Note that the actual update of the 
directories and the system status report- 
are delayed until completion of the 
execution of PROGB, when /6 is read. From 
a system design standpoint this is not 
desirable because of possible operational 
problems. Making the execution of PROGB a 
separate job avoids any difficulties. All 
core image library directories are updated 
at /£. This is time consuming and should 
not be done for each module cataloged. 
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COMPILE AND EXECUTE EXAMPLE 



1. 
2. 
3. 
4. 



// JOB COMPEXEC 

* COMPILE OR ASSEMBLE, LINK EDIT AND EXECUTE 

* SINGLE PHASE , MULTIPLE OBJECT MODULES, BACKGROUND PROGRAM 

* SEQUENTIAL DASD FILES TO BE PROCESSED 

* INPUT TO LINKAGE EDITOR FROM LANGUAGE TRANSLATOR, RELOCATABLE LIBRARY AND SYSIPT. 
// ASSGN SYSLNK, X* 190* 

// OPTION LINK 

PBASE PROGA,S 
// EXEC COBOL 



COBOL source statements 



/* 



INCLUDE SUBRX 
5. INCLUDE 



Relocatable object module 



/* 



6. ENTRY BEGIN1 
// EXEC LNKEDT 

7. Any job control statements required for PROGA execution. 
// EXEC 

Any input data required for PROGA execution. 
/* 



Explanation for Compile and Execute 



The language translators provide the option 
of placing their output on SYSLNK rather 
than SYSPCH. Because the linkage editor 
uses SYSLNK for input, a program can be 
assembled or compiled, then linkage edited 
and executed. This operation, known as 
assemble/compile and execute, is 
illustrated by this example. 



All three sources of object module input 
to the linkage editor are used: SYSIPT, 
the relocatable library, and the output 
from a language translator. It is assumed 
that the phase is executed in the 
background partition, and that only 
sequential DASD files or unlabeled tape 
files are processed. 



Statement 1 ; The SYSLNK assignment is 
given to illustrate the relationship to the 
OPTION statement, although it is not 
required because of the assumed 
configuration . 



Statement 2 : Because SYSLNK is assigned, 
the OPTION LINK statement sets the link 
indicator switches. 

Statement 3 ; The PHASE statement must 
always precede the relocatable modules to 
which it applies; therefore, it is written 
on SYSLNK first for later use by the 
linkage editor. S is the origin point, 
that is, the phase originates with the 
first doubleword at the end of the 
supervisor plus length of the label save 
area (as defined by LBLTYP) plus length of 
the area assigned to the COMMON pool (if 
any). This gives the same effect as * 
gives for a single phase or the first 
phase. As with the *, the S may be used 
with a relocation factor, for example, 
S+1024. The factor must always be 
positive, because a negative factor could 
cause the origin point to overlay the 
supervisor . 

Statement 4 : The appropriate language 
translator is called (in this case, COBOL). 
The normal rules for compiling are 
followed; the source deck must be on the 
unit assigned to SYSIPT and the /* defines 
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the end of the source data. Because the 
LINK switches are set, the output of the 
language translator is written on SYSLNK. 
Except for PL/I, FORTRAN (F) and the 
ASSEMBLER (F) and 14K variant, the DECK 
option is ignored when SYSLNK is used. 

Statement 5 ; The INCLUDE SUBRX statement 
is written on SYSLNK. The linkage editor 
retrieves the named module from the 
relocatable library. Because the operand 
is blank, the next INCLUDE statement 
signifies that the relocatable module is on 
SYSIPT. The data on SYSIPT is copied on 
SYSLNK until the /* statement. 

Statement 6 ; The ENTRY statement is 
written on SYSLNK as the last linkage 
control statement. The symbol BEGIN1 must 
be the name of a CSECT or a label 
definition defined in the first phase. The 
address of BEGIN1 becomes the transfer 
address for the first phase of the program. 
The ENTRY statement is used because the 
user wishes to provide a specific entry 
point rather than to use the point 
specified in the END record or the load 
address of the phase. The ENTRY statement 
affects the first, or only, phase. 

Statement 7 : No LBLTYP statement is 
required, because only sequential DASD 



files are to be processed. The rest of the 
statements follow the same pattern as 
discussed in the Linkage Editing and 
Execute example. The input from SYSLNK to 
the linkage editor is: 

PHASE PROGA,S 

Relocatable module produced by COBOL 

compilation 
INCLUDE SUBRX 

Relocatable module from SYSIPT 
ENTRY BEGIN1 

If an error is detected during 
compilation of a source program, the LINK 
option is suppressed. Under these 
circumstances the EXEC LNKEDT and EXEC 
statements are ignored in this example. 
This LINK option suppression should be kept 
in mind if a series of programs is to be 
compiled and cataloged as a single job. 
Failure of one job step would cause failure 
of all succeeding steps. Remember that an 
OPTION LINK cannot be given if OPTION CATAL 
is in effect, because message ISInD 
(STATEMENT OUT OF SEQUENCE) results. This 
is an error in instruction to the system 
because CATAL has functions that must be 
performed when the next /S statement is 
read. Therefore, the CATAL switch must 
remain on, and linkage editing only cannot 
be performed. 
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CATALOG FOR PHASE OVERLAY EXAMPLE 



// JOB MOLTPHAS 

* LINK EDIT AND CATALOG TO CORE IMAGE LIBRARY 

* MULTIPLE PHASES, MULTIPLE OBJECT MODULES, BACKGROUND PROGRAM 

* NO LABELED TAPE OR NONSEQUENTIAL DASD FILES TO BE PROCESSED 
// ASSGN SYSLNK,X*190' 

1. // OPTION CATAL 

2. PHASE PHASEA, ROOT 
INCLUDE MODI 

3. PHASE PHASEB,* 
INCLUDE MOD2 

4 . PHASE PHASEC , PHASEB 
INCLUDE MOD3 

5. // EXEC LNKEDT 
/g 



Explanation for Catalog for Phase Overlay 



any). Only the first phase statement is 
permitted to specify ROOT. 



Sometimes it is not possible to bring an 
entire program into main storage because it 
requires more bytes of main storage than 
are available. To solve this problem the 
program can be broken into separate phases 
that can be brought into main storage as 
required, overlaying all or part of another 
phase if desired. The linkage editing of 
three cataloged relocatable modules into 
phases for overlay is illustrated by this 
example . 

Statement 1 ; The OPTION CATAL sets the 
switches so that the phases can be linkage 
edited and cataloged into the core image 
library. 

Statement 2 ; PHASEA is considered the ROOT 
phase, that is, it is always resident in 
main storage during program execution. The 
origin point is the first doubleword 
address after the supervisor plus length of 
the label save area (if any) plus length of 
the area assigned to the COMMON pool (if 



Statement 3 ; The * in the PHASE card for 
PHASEB causes M0D2 to be linkage edited at 
the end of PHASEA. 

Statement 4 ; Because PHASEB is specified 
as the load address of PHASEC, it is 
linkage edited into the same address as 
PHASEB. The symbol that designates the 
origin point may be a previously defined 
phase name as in this example, a previously 
defined control section, or a previously 
defined external label. A plus or minus 
relocation factor may be used (for example, 
PHASE2+100) . 

Statement 5 ; The EXEC LNKEDT causes all 
three phases to be linkage edited and 
cataloged. When the phases are executed, 
the ROOT phase normally is loaded by the 
system loader. The other phases would 
probably be brought into main storage by 
means of the FETCH or LOAD macro issued by 
the calling phase. 
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SUBMODULAR STRUCTURE EXAMPLE 



// JOB SUBMOD 

* LINK EDIT AND CATALOG TO CORE IMAGE LIBRARY 

* MULTIPLE PHASES, ONE OBJECT MODULE (SUBMODULAR STRUCTURE) 

* BACKGROUND PROGRAM, NO LABEL STORAGE RESERVATION 
// ASSGN SYSLNK, X* 190* 

// OPTION CATAL 

1. PHASE PHASEl,ROOT 
INCLUDE , ( CSECT1 , CSECT 3 ) 

2. PHASE PHASE2,* 
INCLUDE , (CSECT2,CSECT5) 

3. PHASE PHASE3 , PHASE2 
INCLUDE , (CSECT4,CSECT6) 

H . INCLUDE 



Relocatable object deck 
/* 
// EXEC LNKEDT 



Explanation for Submodular Structure 



Several relocatable modules are structured 
into several phases. In this example, a 
single object module is broken into several 
phases. The object module is composed of 
CSECT1-CSECT6. It is structured into three 
phases with overlay. The module is not 
cataloged in the relocatable library. Only 
the PHASE AND INCLUDE statements are 
discussed. 



Statement 1 ; The INCLUDE statement tells 
the linkage editor to place CSECT1 and 
CSECT3 into PHASEl. The sequence in which 
the CSECTs are linkage edited is determined 
by the sequence in the input module rather 
than the sequence in the INCLUDE statement. 
(CSECT3,CSECTl) would give the same result 
as (CSECT1,CSECT3) . The sequence can be 
controlled by issuing separate INCLUDE 
statements. For example, INCLUDE , (CSECT3) 
followed by INCLUDE , (CSECTl) causes CSECT3 
to be linkage edited before CSECTl, 
regardless of the sequence in the object 
module. 



Note that the first operand is missing 
in the INCLUDE statement, as indicated by 
the leading comma. This format of the 
INCLUDE statement searches the next 
succeeding object module on SYSLNK to 
locate the named CSECTs. See Statement 4. 



Statement 2 : The INCLUDE statement causes 
CSECT2 and CSECT5 to be used for PHASE2. 
This phase is located at the end of PHASEl. 



Statement 3 ; PHASE 3 is made up of CSECT4 
and CSECT6 and overlays PHASE2 because its 
origin point is at the same address as 
PHASE2. 



Statement Q : This INCLUDE statement with a 
blank operand is required to write the 
object module that follows in the card 
reader onto SYSLNK, to satisfy the INCLUDE 
statements with a blank first operand. 



With the sequence of statements shown in 
the example, the PHASE and INCLUDE 
statements are read from SYSRDR. However, 
it is permissible to read PHASE and INCLUDE 
statements from SYSIPT. To do this. 
Statement 4 (INCLUDE blank) is placed ahead 
of Statement 1. The INCLUDE with the blank 
operand directs job control to read the 
following data (which includes the PHASE, 
INCLUDE, and then the object module) on 
SYSLNK from SYSIPT to the /* statement. If 
SYSRDR and SYSIPT are separate devices, 
take care to place the PHASE and INCLUDE 
statements on the correct device. 



PHASEl is located at the end of the 
supervisor plus length of the label save 
area, and the COMMON area (if any) . 
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PHASE and INCLUDE statements can also be This form of the INCLUDE statement causes 

in the relocatable library. If the object the linkage editor to search the module 

module is in the relocatable library under that follows the last INCLUDE statement in 

the name MODI, the following changes are the library for the required control 

made: sections. 

1. Remove Statements 1 through 3 r and add 
module name to Statement 4. 

// JOB SUBMOD 
// OPTION CATAL 
INCLUDE MODI 
// EXEC LNKEDT 

2. When the relocatable module is 
cataloged to the library, precede it 
with the following statements: 

PHASE PHASE1,* 

INCLUDE M0D1,(CSECT1,CSECT3) 

PHASE PHASE2,* 

INCLUDE MODI, (CSECT2, CSECT5) 

PHASE PHASE3,PHASE2 

INCLUDE MODI , (CSECT4 , CSECT6 ) 

Relocatable object deck 
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SELF-RELOCATING AND MULTIPLE LINK EDITS EXAMPLE 



// JOB MULTCATL 

* SEVERAL LINK EDITS AS A SINGLE JOB 

// OPTION CATAL 

1. PHASE PROG1,+0 
INCLUDE PROG1 

// EXEC LNKEDT 

2. PHASE PROG2,* 
INCLUDE 

Relocatable object module 
/* 
// EXEC LNKEDT 

PHASE PROG3,* 

INCLUDE PROG 3 
// EXEC LNKEDT 
/£ 
// JOB LINKGO 

3. // OPTION LINK 

PHASE PROG4,* 
INCLUDE 

Relocatable object module 

/* 

// EXEC LNKEDT 

Any job control statements required for PROG4 execution. 
// EXEC 



/* 



Any input data required for PROG4. 



PHASE PR0G5,* 
INCLUDE PROG5 
// EXEC LNKEDT 

Any job control statements required for PROG5 execution. 
// EXEC 



/* 



Any input data required for PROG5. 



Explanation for Self-Relocating and 
Multiple Link Edits 



The linkage editing requirements for a 
self-relocating program and the combining 
of several cataloging or link- and- execute 
job steps into a single job are illustrated 
in this example. Use discretion in 
deciding how many steps should be combined 
before a /6, because a failure in one step 
can cause successive steps to be bypassed 
unnecessarily. 

Statement 1 : The +0 displacement as the 
origin part for PROG1 designates this 
program as self-relocating. Once this 
program is cataloged to the core image 
library, it may be executed in any 
partition. It can be initiated into the 
background partition by job control, if the 
supervisor was generated with 



multiprogramming capabilities. A non-MPS 
supervisor will give message 0P77I 
(CANCELED DUE TO INVALID ADDRESS). 
However, the program can be loaded by using 
the LOAD macro in a calling phase. 



Statement 2 : PROG 2 and PROG3 are linkage 
edited and cataloged as job steps within 
the job MULTCATL. Note that OPTION CATAL 
holds for these steps. 



Statement 3 ; A new job is initiated 
because the succeeding job steps are linked 
and executed without cataloging. (OPTION 
LINK cannot be issued when OPTION CATAL is 
in effect. ) Note that OPTION LINK need not 
be reissued before the next job step. 
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Checkpoint/Restart 



When a background program or a batched- job 
foreground program is expected to run for 
an extended period of time, provision may 
be made for taking checkpoint records 
periodically during the run. The records 
contain the status of the job and system at 
the time the records were written. Thus, 
they provide a means of restarting at some 
midway point rather than at the beginning 
of the entire job, if processing must be 
terminated for any reason before the normal 
end of job. 

For example, some malfunction, such as a 
power failure, may occur and cause such an 
interruption. If checkpoint records are 
written periodically, operation can be 
restarted with a set of checkpoint records 
written before the interruption. These 
records contain everything needed to 
reinitialize the system when processing is 
restarted. 

Any programmer logical unit 
(SYSOOO-SYSmax) assigned to tape, or the 
2311, 2314, or 2319 can be used for 
recording checkpoints if the proper file 
definitions are made and the correct label 
statements are submitted. Checkpoints must 
not be taken on ASCII tape files. 

The Disk Operating System includes 
routines to take checkpoint records and to 
restart a job at a given checkpoint. The 
checkpoint and restart routines are 
included in the core image library when the 
system is generated. The checkpoint 
routine is executed in the logical 
transient area and is called in response to 
a CHKPT macro instruction in the problem 
program. The restart routine is called by 
job control when it reads a RSTRT control 
statement. When a program is restarted, 
the user must reissue any STXIT macro 
instructions that are desired because the 
STXIT linkages established before the 
checkpoint was taken are destroyed. 
Checkpoint/restart does not save or restore 
floating point registers. (If needed, 
these registers should be stored in the 
problem program area before issuing CHKPT 
macro, and restored in a user restart 
routine . ) 

Only background programs or batched- job 
foreground programs may be checkpointed. 
Checkpoint records are written on a 2311, 
2314, or 2319 DASD or on magnetic tape. 
Each checkpoint is uniquely identified. 
When it is restarted, the RSTRT control 
statement specifies which checkpoint is to 
be loaded. If multireel files are being 
used, the operator must be aware of which 
reels were being processed when the 
checkpoint was taken. 



Multitasking users should only issue the 
CHKPT macro in the main task with no 
subtasks attached. In addition, no tracks 
on any DASD should be in the hold state. A 
multitasking abnormal termination routine 
should not contain a CHKPT macro. 
Checkpoints should be taken while a program 
is running successfully, not while it is 
canceling. Checkpointed programs must be 
restarted in the same partition in which 
they were checkpointed. Multiple jobs 
maybe checkpointed on the same tape. 

Checkpoint records written by previous 
versions of the system are not acceptable 
to the current version of the system. 
However, if they are embedded on magnetic 
tape, they are bypassed by the current 
version. 

It is possible to increase partition 
allocation between the time the checkpoint 
is taken and the time the program is 
restarted, if the starting address of the 
partition remains unchanged. 



PROBLEM PROGRAM RESPONSIBILITIES 



Use of CHKPT Macro 



Any partition, except a foreground 
partition in a single program mode, can 
issue the CHKPT macro successfully. If 
multitasking, only the main task can 
successfully checkpoint. CHKPT is ignored 
when issued by a subtask, a foreground 
partition in single program mode, or in any 
of the following additional conditions: 

1. The device on which the checkpoint 
records are to be written is not a 
magnetic tape or a disk pack. (The 
device must be a 2311, 2314, or 2319 
disk if the filename operand is 
present . ) 

2. End of reel is detected while writing 
the checkpoint on tape. 

3 . The area on disk is not large enough 
for a single checkpoint. 

4. The macro is issued by a 
teleprocessing program that has any 
I/O operation (s) pending on a 
teleprocessing device. 

5. The user-specified end address is 
greater than the end of the problem 
program area. 

6. The CHKPT macro is issued before the 
disk checkpoint file is opened. 
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7. Any of the required DTFPH parameters 
for the disk checkpoint file contain 
errors. 



CHKPT Macro 



9. 



If a subtask is attached in the 
partition being checkpointed . 



If any DASD track for the partition 
being checkpointed is in the HOLD 
state. 



r t t 

| Name | Operation | Operand 
j. + + . 



H 



Note ; Checkpoint records are not 
permitted on ASCII tape files. 

If a checkpoint is ignored, control 
returns to the user with binary zeros in 
register 0. Otherwise, register contains 
the appropriate checkpoint number (in 
unpacked decimal) . 



Checkpoints are usually taken after a 
specified period of time has elapsed, or 
after a certain volume of input is 
processed. When multitasking, use the 
following as a guide for selecting a 
method: 



The multitasking operation requires 
checkpoints to be taken on a time 
interval basis. Therefore, at main 
task execution time, a STXIT macro 
establishes linkage for an interval 
timer interrupt. In the main task 
interval timer routine, the problem 
program issues WAIT macros to wait for 
the detachment of each subtask in the 
partition, and then takes the 
checkpoint. If the main task must 
take an immediate checkpoint, the 
interval timer routine in the main 
task must first detach all subtasks, 
disregarding current processing, 
before it can successfully issue the 
CHKPT macro. 



2. The multitasking operation requires 
checkpoints to be taken on a volume 
basis. Therefore, the main task 
attaches the subtasks necessary to 
perform the job, and then issues WAIT 
macros to wait for each subtask in the 
partition to detach. Each subtask 
keeps a count on the unit of work to 
be performed and detaches when it is 
finished. When all subtasks are 
detached, the main task can take the 
checkpoint. 

After the checkpoint is taken, the main 
task can then either attach more, or the 
same, subtasks to continue processing. 



name 



CHKPT | SYSnnn, /restart address! 

I \ (rl) f 

I 

|[~,/end address)"] r/tpointerfll 
iLt <r2) /JLt (r3) /Jl 



1 1", /dpointer)"! f, /Filename) "I 

L x _ \V\ _ < r _ 4 >__j-U- L (r5 L_U_j 

SYSnnn specifies the logical unit on which 
the checkpoint information is stored. It 
must be a magnetic tape or a disk pack. 
(See Checkpoint File .) 

Restart address (or rl) specifies a 
symbolic name of the problem program 
statement (or register containing the 
address) at which execution is to restart 
if processing must be continued later. 

End address (or r2) is a symbolic name (or 
register containing the address) of the 
uppermost byte of the problem program area 
required for restart. This address must 
follow the logic modules being included 
from the relocatable library. 

If this operand is omitted, all of main 
storage allocated to the partition are 
checkpointed. 

This operand provides two advantages: 

1. Less time and space is required for 
recording the checkpoint record set. 

2. If a program using 24K of storage is 
being run in a larger system and only 
24K is checkpointed, that program can 
be restarted, either on a 2 UK system 
or as a 2 UK partition in a 
multiprogramming system. 

Tpointer (or r3) is the symbolic name of an 
eight-byte field contained in the problem 
program area. (See Repositioning Magnetic 
Tape .) 

Dpointer (or rU) is the symbolic name of a 
DASD operator verification table that the 
user can set up in his own area of main 
storage. (See DASD Operator Verification 
Table .) 

Filename (or r5) is used only for 
checkpoint records on disk. It is the name 
of the associated DTFPH macro. (See 
Checkpoint on Disk .) Special register 
notation cannot be used with any of these 
operands . 
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Information That Is and Is Not Saved : When CHECKPOINT FILE 
the CHKPT macro is issued, the following 
information is saved: 



Information for the restart and other 
supervisor or job control routines. 



• The general registers. 



• Bytes 8-10 and 12-45 of the 
communication region. 



The checkpoint information must be written 
on a disk pack or a magnetic tape (either 
7- or 9-track, EBCDIC only). The 7-track 
tape can be in either data conversion or 
translation mode; however, the magnetic 
tape unit must have the data conversion 
feature. On 7-track tapes, the 20-byte 
checkpoint header and trailer labels are 
written in the mode of the tape (Figure 
3.9). The data records are written in data 
convert mode, odd parity. 



The problem program area (see End 
Address Operand) . 



• All DASD file protection extents 
attached to logical units belonging to 
the checkpointed program. 

The following information is not saved: 

• The floating point registers. (If 
needed, these registers should be 
stored in the problem program area 
before issuing CHKPT, and restored in a 
user restart routine.) 

• Any linkage to user routines set by the 
STXIT macro. (If needed, STXIT should 
be used in user's restart routine.) 

• Any timer values set by the SETIME 
macro. (If needed, SETIME should be 
used in a user's restart routine.) 

• The program mask in problem program 
PSW. (If other than all zeros is 
desired, the mask should be reset in 
user ' s restart routine . ) 



NOTES FOR DASD AND MICR FILES 



DASD system input or output files (SYSIPT, 
SYSLST, etc.) must be reopened at restart 
time. In the user's restart routine, the 
programmer must be able to identify the 
last record processed before checkpoint. 

Magnetic Ink Character Reader (MICR) 
files require the DTFMR supervisor linkages 
to be initiated at restart time. This can 
be accomplished by reopening the MICR file 
in the user's restart routine. Because the 
OPEN macro clears the document buffer, the 
problem program must disengage the device 
and process all follow up documents in the 
document buffer before taking each 
checkpoint. 



Checkpoints On Tape 



The programmer can either establish a 
separate file for checkpoints or embed the 
checkpoint records in an output data file 
(EBCDIC only) . When the data file is read 
at a later time using logical IOCS, the 
checkpoint records are automatically 
bypassed. If physical IOCS is used, the 
user must program to bypass the checkpoint 
record sets. 

If a separate magnetic tape checkpoint 
file with standard labels is maintained, 
the labels should be either checked by an 
OPEN routine or bypassed by a MTC command 
before the first checkpoint is taken. 



Checkpoints On Disk 



If checkpoints are written on disk, the 
following must be observed: 

1. Define area of disk to be used by 
writing a DTFPH macro and using a 
DLBL, EXTENT label set. 

2. The number of tracks required is 
computed as follows: 



x_+ y 
1 + 30 20 + c 

18 z 



where : 

n = the number of sets of checkpoint 
records to be retained. (When the 
defined extent is full, the first 
set of checkpoint records is 
overlaid.) 

c = The number of bytes to be 

checkpointed in the user's problem 
program up to the end address 
specified in the CHKPT macro 
operand. 
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x = The number of disk extents 
including nonover lapping 
split-cylinder extents. If 
split-cylinder extents overlap on 
the same cylinder, the number of 
extents counted is the one used by 
the program. (This number is zero 
if OASD file-protect is not used. ) 

y = same as preceding for 2321. 

z = 3625, if checkpoint records are 
written on a 2311. 7249, if 
checkpoint records are written on 
a 2314/2319. 

For each division, the remainder is 
rounded to the next highest whole 
number before multiplying by n. 



3. Open the area on disk by issuing an 
OPEN to the DTFPH. 



4. Issue a CHKPT macro that points to the 
DTFPH to be used. 

5. When restarting checkpointed jobs, the 
DTFPH filename is specified in the 
RSTRT job control card. 

6. Each program can use a common 
checkpoint file or define a separate 
one. If a common file is used, only 
the last program using the file can be 
restarted. 

See Figure 3 . 6 for an example using the 
checkpointed facility on disk. 



r t 

PAYROLL 



CHKPDSK 



START 
DTFPH 
OPEN 
CHKPT 

END 



DEVICE=2311 , MOUNTED=S INGLE , TYPEFLE=OUTPUT 



CHKPDSK 



SYS 004, RSTRT , END , , DVER , CHKPDSK 



// JOB CHKPT 

ASSGN SYS004,X , 190* 

ASSGN SYSOOO^'ISO* 

ASSGN SYS001,X , 181 t 

ASSGN SYS002,X , 182" 
// DLBL CHKPDSK,* CHECKPOINT FILE*,,, 
// EXTENT SYS004,DOS-II,,,1900,89 
// EXEC PAYROLL 



L 



Figure 3.6. Using Checkpoint Facility on Disk 
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REPOSITIONING I/O FILES 



The I/O files used by the checkpointed 
program must be repositioned on restart to 
the next record that the user wants to read 
or write. The checkpoint facility does not 
provide aids for repositioning unit record 
files. The programmer must establish his 
own repositioning aids and communicate 
these to the operator, when necessary. 
Some suggested ways are: 

1. Take checkpoints at a logical breaking 
point in the data, such as paper tape 
end- of -reel. 

2. Switch card stackers after each 
checkpoint. 

3. Print information at the time of 
checkpoint to identify the record in 
process. 

H. Issue checkpoints on operator demand. 

User sequential DASD input, output, or work 
files require no repositioning. 

When updating DASD records in an 
existing file, the programmer must be able 
to identify the last record updated at the 
time of the checkpoint in case he needs to 
restart. This can be done in various ways: 

1. Create a history file to record all 
updates by dumping an image of the 
direct access record on tape as soon 
as it has been read. When a restart 
is initiated, these records can be 
used to rewrite the file and establish 
the status that existed when the 
corresponding checkpoint was taken. 
When this is completed, normal restart 
procedures are accomplished and 
reprocessing begins. 

2. Create a field in updated records to 
identify the last transaction record 
that updated it. This field can be 
compared with each transaction at 
restart time. 



Repositioning Magnetic Tape 



Checkpoint provides some aid in 
repositioning magnetic tape files at 
restart. Files can be repositioned to the 
record following the last record processed 
at checkpoint. 



The fourth operand of the CHKPT macro 
points to two V-type address constants that 
the user specifies in his coding. The 
order of these constants is important. 



1. The first constant points to a table 
containing the filenames of all the 
logical IOCS magnetic tape files that 
are to be repositioned. 

2. The second constant points to a table 
containing repositioning information 
for physical IOCS magnetic tape files 
that are to be repositioned. 

3. If the first, second, or both 
constants are zero, no tapes processed 
by logical, physical, or both types of 
IOCS, respectively, are repositioned. 



Name 



I 

T 
POINTER 



I 

y 

LOGICL 



l 

T 

PHYSCL 



I 
I 
I 
I 

T 
fi I enamel 



Operation 



CHKPT 



Operand 



SYSOOx^rD^POINTER 
I 



DC 



V(LOGICL) 

V(PHYSCL) 
i 
I 
. I 



CNOP 



DC 



DC 



2,4 

H'n' number of entries 
as follows. 



| — V(filenamel) 
V(filename2) 



V(filenamen) 



DC 



symbolic DTF 
name of each 
tape file to 
be repositioned 
at restart 



H'n' number of entries 
as follows. 



3H 



3H 



six bytes (3 halfwords) 
for each tape file that 
is to be repositioned 
at restart. 



DTFxx 



The following discussion presents the Figure 3.7. 
procedure in correlation with Figure 3.7. 



Procedure for Building Tape 
Repositioning Tables 
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If the tables are contained in the same 
CSECT as the CHKPT macro, the constants may 
be defined as A-type constants. The user 
must build the tables discussed. Each 
filename in the logical IOCS table points 
to the corresponding DTF table where IOCS 
maintains repositioning information. The 
user should note the following: 



Magnetic tapes with nonstandard labels 
should be repositioned past the labels 
at restart time (presumably the labels 
are followed by a tapemark so that 
f oreward space file may be used) . 



If a tape that is to be repositioned 
is processed with nonstandard labels 
and is read backwards, the user must 
keep a physical IOCS repositioning 
table, because the physical record 
count kept by IOCS will be incorrect. 
The physical record count must be the 
number of forward reads necessary for 
restart to position the tape. 



3. Restart does not rewind magnetic tapes 
when repositioning them. 



A multifile reel should be 
prepositioned to the beginning of the 
desired file. 



The entries in the physical IOCS table are 
as follows: 



First half word : hexadecimal representation 
of the symbolic unit number of the tape 
(copy from CCB bytes 6 and 7) . 



Second half word : number of files within 
the tape in binary notation. That is, the 
number of tapemarks between the beginning 
of tape and the position at checkpoint. 



Third half word : number, in binary 
notation, of physical records between the 
preceding tapemark and the position at 
checkpoint . 



DASD Operator Verification Table 



If the Dpointer operand in the CHKPT macro 
is used, the user can build a table in his 
own area of main storage to provide the 
symbolic unit number and the bin (cell) 
number of each DASD file used by his 
program. At restart, the volume sequence 
number of these files is printed on SYSLOG, 
and the operator can verify them. 



5. The correct volume of a multivolume 
file must be mounted for restart. 



6. For tapes with a standard VOL label, 
restart writes the file serial number 
and volume sequence number on SYSLOG, 
and gives the operator the opportunity 
to verify that the correct reel is 
mounted. 



The entries in the DASD operator 
verification table must consist of the 
following two half words, in the order 
stated : 



The symbolic unit in hexadecimal 
notation copied from CCB bytes 6 and 
7. 



IOCS can completely reposition files 
on system logical units (SYSIPT, 
SYSLST, etc) , if the tape is not 
shared with any other program and if 
the user keeps a physical IOCS 
repositioning table. However, if a 
system logical unit file is shared 
with other programs, a problem exists. 
Output produced after the checkpoint 
is duplicated at restart. Input 
records must be reconstructed from the 
checkpoint, or the user restart 
routine must find the last record 
processed before checkpoint. 



The bin (cell) number in hexadecimal 
notation is always zero, except for a 
2321, in which case the bin number 
varies with the cell (0-9) being 
verified. 



There must be one table entry for each 
DASD unit to be verified by the operator. 
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See Figure 3.8 for the procedure for 
building a DASD operator verification 
table. 



Name 


OperaH< 


Dtl 




Operand 




CHKPT 




SYSOOx, RSTRT, END, , DVER, CHKPDSK 

j ; 


r — 

i 

i 








1 
1 






i 


CNOP 




2,4 




t 










DVER 


DC 


| 


H'n' 

2H 

• 

• 
• 


number of entries 
as follows: 

4 bytes (2 halfwords) 
are required for each 
DASD so that the 
operator can verify 
each volume sequence 
number at restart time. 


l 

1 






2H 




t 










CHKPDSK 


DTFPH 









Figure 3.8. Procedure for Building DASD 
Operator Verification Table 



BYPASSING EMBEDDED CHECKPOINT RECORDS ON 
TAPE WITH PHYSICAL IOCS 



The checkpoint information saved is written 
as a set of magnetic tape records 
consisting of a 20-byte header record, as 
many core-image records as required to save 
the necessary parts of main storage, and a 
20-byte trailer record identical to the 
header. See Figure 3.9 for the format of 
header and trailer record. 

If checkpoint sets are embedded in a 
file being read with physical IOCS, they 
must be recognized and bypassed. On any 
mode input tape, checkpoint sets may be 
identified by the first 12 bytes of the 
header or trailer records. Note that when 
reading backwards, the checkpoint header 
occupies the 20 low-order bytes of the 
input area. 



j Bytes | Contents j 

0-11 |/// CHKPT // 

12-13 | The number, in binary, of core 

image records following the header. 

14-15 | The total number, in unpacked 

hexadecimal, of records following 
the header. 

16-19 | The serial number of the check 
point . 



Figure 3.9. Format of the Checkpoint 
Header/Trailer Records 

When bypassing checkpoint sets, three 
methods are possible: 

1. Go into a read loop (forward or 
backward) until the checkpoint trailer 
(header if backward) is encountered. 

2. Extract the count from bytes 12-13 of 
the header (or trailer if backwards) , 
add 2 to this, and forward-space (or 
backspace) that number of records. 
Read commands could also be used. 

3. Extract bytes 14-15 of the header (or 
trailer if backwards) , pack and 
convert the field to binary, and 
forward-space (or backspace) that 
number of records. Read commands 
could also be used. 

When bypassing checkpoint sets on 
7-track tapes in translate mode, only 
method 3 can be used and only forward- space 
(or backspace) record commands (not reads) 
can be used. Reads would create data 
checks. 



BYPASSING CHECKPOINT RECORDS ON TAPE WITH 
LOGICAL IOCS 



When a tape input file contains checkpoint 
records interspersed among the data 
records, the DTFMT macro parameter 
CKPTREC=YES is required. When this 
parameter is specified, logical IOCS 
bypasses the embedded checkpoint records. 
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RESTARTING CHECKPOINTED PROGRAMS 



Job control prepares the system for 
restarting from a checkpoint by loading the 
restart program that repositions tape 
units, reinitializes the communication 
region, and stores the information from the 
RSTRT statement. The restart program 
handles the actual restarting of the 
problem program. 



RSTRT Statement 



When a checkpoint is taken, the 
completed checkpoint is noted on SYSLOG. 
Restarting can be done from any checkpoint 
record, not just the last. The job name 
specified in the JOB statement must be 
identical to the job name used when the 
checkpoint was taken. The proper I/O 
device assignments must precede the RSTRT 
control statement. 

Assignment of input/output devices to 
symbolic unit names may vary from the 
initial assignment. Assignments are made 
for restarting jobs in the same manner as 
assignments are made for normal jobs. 



The restart facility allows the programmer 
to continue execution of an interrupted job 
at a point other than the beginning. The 
procedure is to submit a group of job 
control statements including a restart 
(RSTRT) statement. The control statements 
necessary to restart a job from a 
checkpoint are: 

1. JOB statement specifying the same job 
name used when the checkpoint was 
taken. 

2. ASSGN statements for assigning I/O 
devices to the symbolic unit names. 

3. RSTRT statement specifying the unit 
that contains the checkpoints and the 
checkpoint ID number taken from the 
message printed when the checkpoint 
was taken. The format of the RSTRT 
statement is: 

// RSTRT SYSxxx,nnnn, filename 

SYSxxx Symbolic unit name of the device 
on which the checkpoint records 
are stored. This unit must have 
been previously assigned. 

nnnn Identification of the checkpoint 
record to be used for restarting. 
This serial number is four 
characters and corresponds to the 
checkpoint identification used 
when the checkpoint was taken. 
The serial number is supplied by 
the checkpoint routine. 

filename Symbolic name of the 2311 or 2314 
disk checkpoint file to be used 
for restarting. It must be 
identical to the filename of the 
DTFPH used to describe the disk 
checkpoint file and the fifth 
parameter of the CHKPT macro 
instruction. This operand 
applies only when specifying a 
2311 or 2314 disk as the 
checkpoint file. 



IBM 3211 Printer Support 



The addition of tapeless forms control and 
improvements in the use of the loadable 
print character buffer required special 
programming support for the IBM 3211 
Printer. SYSBTJFLD is the service program 
that loads the Universal Character Set 
Buffer (UCSB) and the Forms Control Buffer 
(FCB) with buffer load programs for the 
3211 printer. SYSBDFLD is self-relocating, 
requires 2K of main storage, and is 
executed as a job step under BJF or SPI. 
It is initiated by the command: 

// EXEC SYSBUFLD 

$$BUFLDR is another 3211 program, called 
by IPL to load the UCSB and FCB buffer 
loads from the core image library. 



System Considerations 



When a 3211 PUB is encountered, the IPL 
program calls the buffer load transient, 
$$BUFLDR. $$BUFLDR in turn calls $$BUCB to 
load the UCSB, and $$BFCB to load the FCB. 
As supplied by IBM, these two phases 
contain : 

$$BFCB the configuration for a 66-line 
page (at 6 lines per inch), with 
56 lines available for printing, 
a channel 1 for line 1, and a 
channel 12 for line 56. 

$$BUCB the character configuration for 
the All train. 

Also, $$BUFLDR sets the UCSB for folding 
and suppressing data checks. 

SYSBUFLD can be used to change the UCSB 
or FCB configurations, or to reload these 
buffers if a hardware failure occurs. 
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Only one FCB load is supplied in the DOS 
system. Additional FCB loads can be 
created using the procedure in the DOS 
System Control and Service listed in the 
Preface . FCB loads can be either cataloged 
in the core image library or can be card 
images. Any of your FCB loads can be 
cataloged in the core image library as 
$$BFCB to enable the IPL program to load 
it. If a phase name is not specified 
during an FCB load, SYSBUFLD loads the 
buffer from SYSIPT. 



All UCSB programs must be cataloged in 
the core image library. They are loaded by 
specifying them in the SYSBUFLD control 
card. 



The four remaining standard train 
configurations (Gil, Hll, Pll, or Til) are 
in the relocatable library under the name 
IJBTRxll, where x is G, H, P, or T. These 
can be cataloged in the CIL to be loaded 
according to the train configuration. 



Non-standard UCSB loads can be created 
following the procedure in the DOS System 
Control and Service listed in the Preface . 
Any of these standard or nonstandard loads 
can be cataloged as $$BUCB to enable the 
IPL program to load that particular train 
configuration. 



Error Recovery Techniques 



The simplest error recovery technique for 
the 3211 printer is specifying ERROPT=RETRY 
in the DTFPR, which sets CCB byte 2, bit 5 
(PRINTOV=YES also sets this bit). This 
causes one automatic retry of the 
equipment-check/command- retry error . 



A more comprehensive technique is 
specifying ERROPT=YES in the PRMOD and 
ERROPT=name in the DTFPR, which sets CCB 
byte 2, bits 5 and 6. These bits indicate 
linkage to your error recovery routine 
named in the DTFPR, and provide automatic 
retry of the equipment-check/command-retry 
error. 

Return from your error recovery routine 
is by register 14. Both registers 14 and 
15 must be saved if LIOCS is used during 
error recovery. 

PIOCS users can provide linkage to error 
recovery by testing the applicable bits in 
the CCB. see Figure 3.10 for the error 
indicators. 

If PIOCS or LIOCS is used, the sense 
information is not available to the user. 
The sense command, issued by the DOS error 
recovery routines, clears the 3211 sense 
information. 
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CCB Byte 


Bit 


Error 


2 


1 


UCSB Parity Check -Line Complete: 

There has been a parity error in at least one position of the UCSB. All characters in the line have been 

printed and line spacing has taken place. The position in error has been cleared, so errors will not be 

encountered during subsequent scans of the UCSB. 

Printer speed is degraded as a result of this error. Full printing speed cannot be regained until the UCSB 

is reloaded. You need a routine to reload the UCSB during the job step, or use SYSBUFLD to reload the 

UCSB before the next job step. 


3 





Equipment Check/Print Check: 

This is a hardware error that has resulted in an incomplete line, but line spacing has taken place. Check 
for possible line position or print quality errors. The line in error must be either accepted or the page 
reprinted (a user -written routine is needed). 


3 


1 


Equipment Check/Print Quality: 

This indicates a hardware error has occurred that caused light or blurred printing. Line spacing has 

taken place. Check for possible print check or line position errors. 

The line in error must be accepted or the page reprinted (a user -written routine is needed). 


3 


2 


Line Position Error: 

This can be a hardware error, a parity error in the FCB, or the result of a skip to a channel code not in 

the FCB. Check for possible print check or print quality errors. 

There is no way to tell where the carriage is positioned relative to the FBC; physical repositioning, as 

well as reloading of the FCB, may be necessary. 


3 


3 


Data Check/Print Check: 

An unprintable character has been sent to the printer. The applicable position (s) in the print line are 

blank and the paper has been spaced. 

The line in error must be either accepted or the page reprinted (a user -written routine is needed). 

Note: Check or reload the UCSB to ensure that the correct load has been used. 


3 


4 


USCB Parity Check/Command Retry: 

There has been a parity error in at least one position of the UCSB. The applicable position(s) in the 

print line is blank, but the paper has not been spaced. Subsequent attempts to print the applicable 

character will result in a data check/print check. 

The UCSB can be reloaded (a user -written routine is needed), and the applicable command (s) 

reissued. 



| Figure 3.10. 3211 Error Status Indicator Bits in the CCB 



Macro Writing 



definition and retain access to all machine 
facilities. 



The macro-definition language discussed 
here provides a systematic means by which 
the DOS/360 assembler language programmer 
can develop macro instructions, thereby 
expanding the set of machine-oriented 
instructions that serve as the basis of the 
assembler language. This enables the 
programmer to reduce programming effort and 
shorten the assembler language source 
programs. With the aid of the macro 
language, any sequence of statements can be 
summarized into a single macro definition. 
Once written, this definition can be stored 
and referred to at any time, thus supplying 
the programmer with precoded routines. The 
programmer only writes a single statement, 
a macro instruction, to access the macro 



Systematic use of macro instructions 
simplifies the coding of programs, reduces 
the frequency of programming errors, and 
encourages the use of carefully 
standardized sequences of assembler 
language statements for routine functions. 



There are two classes of macros in the 
Disk Operating System: system macros, 
which are IBM-written macros supplied with 
the system, and user macros, which are 
defined by the user. The user macros may 
be included in the source program and/or 
may be entered into the source statement 
library. 
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The source statement library contains 
both user and system macro definitions. 
This library, which can be a part of System 
Residence (SYSRES) or a private library, 
eliminates the need for including 
definitions in the source module. 



MACRO INSTRUCTION 



The macro instruction statement is in 
assembler statement format. Symbols are 
used as a shorthand method of representing 
rules, definitions, etc. These macro 
instructions result in a one-for-one 
assembler statement. 

The name field of the macro instruction 
may contain a symbol that is not defined 
unless a symbolic parameter appears in the 
name field of the prototype and the same 
parameter appears in the name field of the 
generated model statement (see The Macro 
Definition ) . 

The operation field contains the 
mnemonic operation code of the macro 



instruction and has to be the same as the 
mnemonic operation code in the source 
program or in the source statement library. 

The placement and order of the operands 
in the macro instruction statement is 
determined by the placement and order of 
the symbolic parameters in the operand 
field of the prototype statement. The 
operand field contains from 0-200 entries, 
separated by commas (entries are commonly 
referred to as parameters) . Any 
combination of up to 255 characters may be 
used as a macro instruction operand if the 
rules concerning apostrophes, parentheses, 
equal signs, ampersands, commas and blanks 
are observed. These are described in the 
Tape Operating Systems Assembler Language 
publication listed in the front of this 
manual. 

The operand may be written in a format 
different than that used for assembler 
language statements. The alternate format 
described here allows the programmer to 
write an operand on each line and allows 
the interspersing of operands and comments 
in the statement. Figure 3.11 illustrates 
the operand formats. 



-t 1 

j Col. 72 j 



r t r 

| Name | Operation! Operand Comments 

I 

NAME1 | OP1 j OPERANDI, OPERAND2, 

JOPERAND3 THIS IS THE NORMAL FORMAT 

I 
NAME2 I OP2 | OPERANDI, THIS IS THE 

|OPERAND2,OPERAND3 ALTERNATE FORMAT 

I 

NAME3 | OP3 j OPERANDI, THIS IS A COMBINATION | x 
| OPERAND2 , OPERAND3 , OPERAND** , | x 

JOPERAND5 OF BOTH FORMATS 

L J J. X 



Figure 3.11. Operand Field Formats 



When a program is written in the Disk 
Operating system macro language (an 
extension of DOS assembler language) , one 
of three macro instruction formats can be 
used: keyword, positional, or mixed. 



Figure 3.12 shows the typical form of a 
keyword macro instruction to be used with a 



keyword macro definition. 



j Name j Operation j Operand j 

|A symbol, j mnemonic | Zero to 100 or 200 j 
| sequence j operation! operands, separated j 
j symbol, or j code jby commas. | 

| not used j | j 

L L - L J 

Figure 3.12. Keyword Macro Instruction 
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Each operand consists of a keyword 
immediately followed by an optional value. 
Nested keywords are not permitted. A 
keyword consists of one to seven letters 
and digits, the first of which must be a 
letter. The operands of a keyword macro 
instruction may be written in any order. 
If an operand is omitted, the comma that 
would have separated it from the next 
operand need not be written. 



The following are valid keyword macro 
instruction operands: 



A4=F , 60«U f 

DUPE4=MEMBER 

S0= 



I Name j Operation j Operand 

| | EXAMPLE |£A, £B,6C,SD, &E, SF 

| | EXAMPLE j 17, *+4,, AREA, FIELD (6) 

L X X 



■H 



j 



Figure 3.1*1. 



Macro Instruction with 
Prototype 



Mixed-mode macro instruction operands 
are a combination of both positional and 
keyword operands. Certain operand entries 
(positional) must be written in a fixed 
order; other operand entries (keyword) can 
be specified in any order. Figure 3.15 
illustrates the mixed-mode macro 
instruction. 



The following are invalid keyword macro 
instruction operands: 



£X4.P3=0(1,*D 



CARDAREA=B+1 



Keyword does not begin 
with a letter. 

Keyword is more than seven 
characters . 



= (TO (8), (AFTER)) No keyword. 



The typical macro instruction is 
positional unless otherwise indicated. The 
positional macro instruction operands are 
written in a fixed order. Figure 3.13 
illustrates the positional macro 
instruction. 



j Name j Operation j Operand j 

j A symbol, j mnemonic | Zero to 100 or 200 j 
| sequence j operation! operands, separated j 
j symbol or j code j by commas . j 

j not used j j j 

L L -J. : J 

Figure 3.15. Mixed Macro Instruction 

The operand consists of two parts. The 
first part corresponds to the positional 
operands and is written in the same way 
that the operand entry of a positional 
macro instruction is written. The second 
part of the operand corresponds to the 
keyword operands. This part is written in 
the same way that the operand entry of a 
keyword macro instruction is written. 
Figure 3.16 illustrates these facilities. 



r r t t 

| Name | Operation | Operand | 

j A symbol, j mnemonic jzero to 100 or 200 j 
j sequence j operation j operands , separated j 
j symbol, or j code jby commas. j 

| not used | j j 

l x — . . x ^ j 

Figure 3.13. Positional Macro Instruction 









|Name|Operat: 

i T i Ir . 


Lon | Operand 

± _ 


I 
j 


j. f 


— 1- 


— 1 


| | MACRO 


I 




|£N |MOVE 


| &TY, SP, £R, 6TO=, &F= 




| SN | STSTY 


|6R,SAVE 




| | L&TY 


|£R,€P,£F 




| IST&TY 


|£R,6P,£TO 




| | L6TY 


|£R,SAVE 











The positional operands, if omitted from 
the macro instruction but appear in the 
prototype, are replaced by the comma that 
would have separated them from the next 
operand. If the last operand is omitted 
from a macro instruction, then the comma (s) 
separating the last operand from the 
previous operand may be omitted. 

Figure 3.14 shows a macro instruction 
preceded by its corresponding prototype 
statement. The third and sixth operands of 
the macro instruction corresponding to the 
third and sixth operands of the prototype 
statement are omitted in this example. 



Figure 3.16. Mixed-Mode Definition 



MACRO DEFINITION 



A macro instruction cannot be assembled 
unless a macro definition is made available 
to the assembler. A macro definition is a 
set of statements that provide the 
assembler with: 

1. The name entry, the mnemonic operation 
code, and the form of the macro 
instruction operand, and 
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The sequence of statements that the 
assembler uses when the macro 
instruction appears in the source 
program. 



Elements of the Macro Definition 



Every macro definition is made up of four 
elements: header statement, prototype 
statement, model statement, and a 
macro-definition trailer statement. 

The macro instruction header and trailer 
statements denote the beginning and end of 
a macro definition respectively. The 
header statement's name field contains 
blanks, the operation field contains the 
word MACRO, and the operand field contains 
blanks. The header statement is the first 
statement of the macro definition. The 
trailer statement follows the same general 
outline as the header statement; only the 
operation field, that contains the word 
MEND, is different. The trailer statement 
must be present to denote the end of the 
macro definition. 

A prototype is defined as an original 
model on which something is patterned. The 
prototype statement of a macro definition 
specifies in the operation column, the name 
of the macro and the format for the operand 
of all macro instructions that make use of 
this definition. This prototype statement 
must be the second statement in the macro 
definition. 

Like the operand of the macro 
instruction, the prototype statement may be 
written in a form different from that used 
for machine or assembler instructions. The 
alternate form is described under The Macro 
Language . 



ATTRIBUTES 



The assembler assigns attributes to macro 
instruction operands and to symbols in the 
program. These attributes may be referred 
to in conditional assembly instructions 
under Conditional Assembly Statements . 

There are six kinds of attributes: 

1. Type (T*): The type attribute of a 
macro instruction is a letter. The 
type attribute may be referred to in 
the operand of a SETC instruction, or 
in character relations in the operands 
of SETB or AIF instruction. The 
letters used with the type attribute 
and their meanings can be found in the 



Assembler Language publication listed 
in the front of this manual. 



2. Length (L*): The length attribute of 
a symbol (or of a macro instruction 
operand that is a symbol) is the 
length of the specified operand. 
Reference to the length attribute of a 
variable symbol is illegal except for 
symbolic parameters in SETA, SETB, and 
AIF statements. Reference must not be 
made to the length attributes of 
symbols whose type attributes are the 
letters M, N, 0, T, or U. 

3 and 4. Scaling (S f ) and Integer (I f ): 
Scaling and integer attributes are 
provided for symbols that name fixed 
point, floating point, and decimal DC 
or DS statement. The programmer may 
refer to the length, scaling, and 
integer attributes in the operand 
field of a SETA instruction, or in 
arithmetic relations in the operand 
fields of SETB or AIF instructions. 

5 . Count Attribute (K • ) : The programmer 
may refer to the count attribute of 
macro instruction operands only. The 
count attribute is a value equal to 
the number of characters in the macro 
instruction operand after substituting 
for variable symbols excluding commas. 
If the operand is a sublist, the count 
attribute includes the beginning and 
ending parentheses and the commas 
within the sublist. The count 
attribute of an omitted operand is 
zero. The count attribute is one of 
the following: 

a. the operand field of a SETA 
instruction, or 

b. in arithmetic relations, the 
operand field of SETB or AIF 
instructions which are part of a 
macro definition can be referenced 
by the user. 

6. Number Attribute (N*) : The number 
attribute of macro instruction 
operands, only, is referenced. The 
number attribute is a value equal to 
the number of operands in an operand 
sublist. The number of operands in an 
operand sublist is equal to one, plus 
the number of commas that indicate the 
end of an operand sublist. If the 
macro instruction operand is not a 
sublist, the number attribute is one. 
If the macro instruction operand is 
omitted, the number attribute is zero. 
Reference may be made to the number 
attribute in the operand field of a 
SETA instruction, or in arithmetic 
relations in the operand fields of 
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SETB and AIF instructions that are 
part of a macro definition. 



Name field entry which can contain 
blanks, a symbol, a symbolic parameter 
or a sequence symbol. 



SUBLIST NOTATION 



A sublist is one or more operands, 
separated by commas and enclosed in paired 
parentheses. An operand of a macro 
instruction may be a sublist. The entire 
sublist, including all operands, commas and 
parentheses is considered one macro 
instruction operand. Each operand entry 
within the parentheses is called a sublist 
member. 

Sublists provide the user with a 
convenient way to refer to a collection of 
macro instruction operands as a single 
operand, or a single operand in a 
collection of operands. For the accessing 
of individual members, the left parenthesis 
of the sublist notation must immediately 
follow the last character of the symbolic 
parameter. A period should not be placed 
between the left parenthesis and the last 
character of the symbolic parameter (Figure 
3.17). 



2. The operation entry may contain any 
machine instruction, conditional 
instruction, assembler instruction, or 
symbolic parameter except COPY, END, 
ICTL, ISEQ and PRINT; or it may 
contain a variable symbol, depending 
on the statement. 



3. The operand entry may contain ordinary 
symbols or variable symbols. After 
substitution, the operand must not be 
greater than 127 characters. Model 
statements must follow the rules for 
paired apostrophes, ampersands, and 
blanks, as macro instruction operands. 

H. The comments field entry which can 
contain descriptive items of 
information about the program is 
inserted after the operand. All 256 
valid characters, including blanks, 
may be used in writing a comment. The 
entry cannot extend beyond the end 
column (normally column 71) and a 
blank must separate it from the 
operand. 



r T 1 - 1 " -i "" " "-" 

j NAME j OPERATION j OPERAND 

L • • 


■ 1 

1 

H 

1 


r — 

HEADER j 
Prototype j 
Model | 
Model | 
Model j 
Model j 
Trailer j 

1— 
1 

MACRO j 
Generated) 
Generated! 
Generated! 
Generated j 

L 


J MACRO 

JADDNUM 

|L 

|A 

|A 

j ST 

j MEND 

1 
JADDNUM 

|L 
|A 
|A 
|ST 
_ x_ _ . 


| &NUM, SREG, SAREA 
|SREG,SNUM(1) 
|&REG,SNUM(2) 
|SREG,SNUM(3) 
j SREG, SAREA 


| (A,B,C),6,SUM 
|6,A 
|6,B 
|6,C 
J6,SUM 
. X _ 


t 

... I 



Figure 3.17. Sublist Illustration 

The operand of the macro instruction 
that corresponds to symbolic parameter 6NUM 
is a sublist. One of the operands in the 
sublist is referred to in the operand entry 
of three of the model statements. 

Model statements are the macro 
definition statements from which the 
desired sequences of machine instructions 
and certain assembler instructions are 
generated. Zero or more model statements 
may follow the prototype statement. A 
model statement consists of one to four 
entries: 



VARIABLE SYMBOLS 



The three types of variable symbols are 
symbolic parameters, SET symbols and system 
variables . 



Symbolic Parameter 



The symbolic parameter consists of an 
ampersand (first character) followed by one 
to seven letters and/or numbers, the first 
of which must be a letter. Symbolic 
parameters appear in prototype and model 
statements. They are assigned values by 
the programmer when he writes a macro 
instruction. The programmer should not use 
6SYS as the first four characters of a 
symbolic parameter. 



Example : 
Valid 

6LOOP2 



Invalid 

62BAC (first character 

after S not letter) 



SREADER SAREA2U56 (too long) 
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SET Symbols 



SET symbols follow the same rules for 
structure as symbolic parameters- SET 
symbols differ from symbolic parameters in 
three ways: 

1. their position in an assembler 
language source program, 

2. how they are assigned values, and 

3. how their assigned values can be 
changed. 



Defining SET Symbols 



A SET symbol must be defined by the 
programmer before it can be used. It is 
defined by appearing as an operand of a 
global or local instruction (GBLA, GBLB, 
GBLC, LCLA, LCLB, LCLC) . Figure 3.18 shows 
the typical format of global and local 
instructions . 

r t t 1 

| Name | Operation | Operand | 



Not used; 
must not 
be present 



GBLA, 
GBLB, 
GBLC, or 



LCLA, 
LCLB, 
LCLC 



One or more variable 
symbols used as 
SET symbols and 
separated by commas. 
(If more than one 
macro defines one 
global SET symbol 
and these macros are 
assembled together, 
the global SET 
symbol value is set 
by the first macro, 
but is not altered 
by subsequent 
macros . ) 



Figure 3.18. Format of Globals and Locals 

A global instruction (GBLA, GBLB, GBLC) 
defines one or more operands as names 
associated with arithmetic, binary, or 
character data. These operands are called 
global SETA, SETB, or SETC symbols. If a 
global instruction is part of a macro 
definition, it must immediately follow the 
prototype statement or another GBLA, GBLB, 
or GBLC. The global definition of these 
operands indicates that each SET symbol is 
defined both inside and outside the 
defining macro and enables communication 
between discrete macros. 

A local instruction (LCLA, LCLB, LCLC) 
defines one or more operands as names 
associated with arithmetic, binary, or 



character data. These operands are called 
local SETA, SETB, or SETC symbols. If a 
local instruction is part of a macro 
definition, it must immediately follow the 
prototype statement and any global 
instructions or another LCLA, LCLB, or 
LCLC. The local definition of these 
operands indicates that each SET symbol is 
defined only within the defining macro. 

The GBLA or LCLA, GBLB or LCLB, GBLC or 
LCLC operands are assigned initial values 
of (X'FO*), (X^OO*), and null character 
(no hexadecimal number) , respectively. 

The SETA, SETB, and SETC symbols are 
assigned the initial values of 0, 0, and 
null character value, respectively. 

The SETA instruction in the operand 
entry is evaluated as a signed 32-bit 
arithmetic value that is assigned to the 
SETA symbol in the name entry. Figure 3. 19 
shows the format of the SETA instruction. 



I 



j 



j Name j Operation j Operand 

| A SETA j SETA (One term, or 

| symbol j jan arithmetic 

j | (expression, not 

| | j less than -2 31 nor 

j j j greater than +2 31 -1. 

Figure 3.19. Format of SETA Instruction 



The expression may consist of one term 
or an arithmetic combination of terms, the 
minimum and maximum values of which are 
-2 3i and +2 3 *-l, respectively. The 
arithmetic value assigned to a SETA symbol 
is substituted for the SETA symbol when it 
is used in an arithmetic expression. 

The SETB instruction may assign the 
binary value or 1 to a SETB symbol. 
Figure 3.20 illustrates the format of this 
instruction. 

r t t 1 

| Name | Operation | Operand | 

± ,. + i 

| A SETB j SETB |A or a 1, (0) or (1), | 
j symbol | jor a logical expression | 
j j j within parentheses | 

L ± . X J 

Figure 3.20. Format of SETB Instruction 

The operand may contain a or a 1 or a 
logical expression enclosed in parentheses. 
No explicit binary zeros or ones are 
allowed in parentheses other than in the 
form (0) or (1). A logical expression is 
evaluated to determine if it is true or 
false. The SETB symbol in the name entry 
is then assigned the binary value 1 or 
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corresponding to true or false, 
respectively . 

The following are valid operand fields 
of SETB instructions: 

UAREA+2 GT 29) 

(T'ST02 EQ *C % ) 

The following are invalid: 

SB (not enclosed in parentheses) 

(T*SP12 EQ "F* SB) two terras in succession 

The SETC instruction assigns a character 
value to a SETC symbol. Figure 3.21 shows 
the format of a SETC instruction. 



r t t 

| Name J Oper at ion | Operand 



A SETC | SETC 
symbol 



jone operand of 
| the type attribute, 
j character expression 
jor a substring 
j notation. A SETA 
| symbol may appear 
| here. 
-X 



Figure 3.21. Format of SETC Instruction 

The character value assigned to a SETC 
symbol may be a type attribute. If the 
type attribute is used, it must appear 
alone in the operand field. 

A character expression usually appears 
in the operand field. A character 
expression consists of any combination of 
characters enclosed in apostrophes. The 
maximum length of a character expression is 
127 characters. The character value 
enclosed in apostrophes in the operand 
field is assigned to the SETC symbol in the 
name entry. The maximum length character 
value that can be assigned to a SETC symbol 
is eight characters. If a value greater 
than 8 is specified, the leftmost 8 
characters are used. 



System Variables 



System variable symbols are assigned values 
automatically by the assembler. There are 
four system variable symbols: 6SYSNDX, 
SSYSPARM, SSYSECT, and SSYSLIST. System 
variable symbols may be used in the name, 
operation, and operand entries of 
statements in macro definitions, but not in 
statements outside of macro definitions 
with the exception of SSYSPARM. They may 
not be defined as symbolic parameters or 



SET symbols, nor may they be assigned 
values by SETA, SETB, and SETC 
instructions . 

The SSYSNDX symbol is assigned the 
four-digit number 0001 for the first macro 
instruction processed by the assembler, and 
it is incremented by one for each 
subsequent inner and outer macro 
instruction processed. SSYSNDX may be 
combined with other characters to create 
unique names for statements generated from 
the same model statement. The SSYSECT 
symbol carries a character value that is 
the name of the last START, CSECT, or DSECT 
statement encountered before the expansion 
of the USING macro. 

The SSYSPARM is specified in the STDJC 
macro at system generation time. SSYSPARM 
allows the user to control conditional 
assembly flow and source code generated 
through the use of the parameter specified 
in the job control OPTION statement. 
SSYSPARM acts as a global SETC, except its 
value is set by the job control OPTION 
statement. 

If no named CSECT, DSECT, or START 
statements occur before a macro 
instruction, SSYSECT is assigned a null 
character value for that macro instruction. 
The SSYSLIST symbol (not available in 
keyword macro definitions) is the symbol 
reference for the entire macro instruction 
operand field. This symbol refers to the 
nth macro instruction operand. If the nth 
operand is a sublist, then SSYSLIST (n,m) 
may refer to the mth operand in the 
sublist, where n and m may be any 
arithmetic expressions allowed in the 
operand field of a SETA statement. 



CONCATENATION 



Concatenation is defined as a linking 
together in a series or chain; a process of 
linking or joining together in a sequence, 
with a specified order. 

If a symbolic parameter in a model 
statement is immediately preceded or 
followed by other characters or another 
symbolic parameter, the characters that 
correspond to the symbolic parameter are 
combined, in the order given in the 
generated statement, with the other 
characters or the characters that 
correspond to the other symbolic parameter. 
This process is called concatenation. When 
a symbolic parameter is concatenated with 
any following character value, the extent 
of the symbol must be defined (delimited) . 
If the first character of the following 
character value is not a recognized 
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delimiter, a special delimiter character (a 
period * . • ) , must be used when the first 
character is a letter, digit, left 
parenthesis or a period. A period is 
optional when the first character is an 
ampersand (6). See Figure 3.22. 



|Name 

L _ _ 


| Operation | Operand | 


r t 

Header j | MACRO 

Prototype j SNAME | MOVE 

Model j SNAME j ST 

Model j | L 

Model j j ST 

Trailer j j L 

j j MEND 
i i 


r i 

|SP,€S,SR1,SR2 | 
|6Rl,&S. UR2) j 
|&Rl,£P.B j 
|SR1,SP.A | 
|6R1,6S. (SR2) j 

|FIELD,SAVE,2,4 | 


r 

Macro | HERE 
i 


|MOVE 


1 
Generated | HERE 
Generated! 
Generated! 
Generated j 

L _ 


|ST 

l L 
|ST 

|L 

X 


|2,SAVEU) | 
J2,FIELDB | 
|2,FIELDA j 
|2,SAVE(4) j 


Figure 3.22. 


Concatenation and Generated 
Coding 



SEQUENCE SYMBOLS 



The name entry of a statement may contain a 
sequence symbol that provides the 
programmer with the ability to vary the 
sequence in which the assembler processes 
statements. These symbols are never 
variables. They name a branch point in the 
definition and consist of a period followed 
by a letter and seven letters and/or 
digits. 

A sequence symbol in the operand entry 
of an AIF or AGO statement (see Conditional 
Assembly Statements ) references the 
statement named by the sequence symbol. It 
can be used in the name entry of any 
statement that does not contain a symbol or 
SET symbol, except a prototype statement, 
or a MACRO, LCLA, LCLB, LCLC, GBLA, GBLB, 
GBLC, ACTR, ICTL, ISEQ, or COPY 
instruction. For example, .READER, .LOOP2, 
.A23456 and .X4F2 are valid sequence 
symbols. 



CONDITIONAL ASSEMBLY INSTRUCTIONS 



The conditional assembly instructions allow 
the programmer to: 

1. Define and assign values to SET 

symbols that can be used to vary parts 
of generated statements and 



2. Vary the number and sequence of 
generated statements. 



These conditional assembly instructions 
give true flexibility to the macro 
definition language. 



There are 13 conditional assembly 
instructions: LCLA, LCLB, LCLC, GBLA, 
GBLB, GBLC, SETA, SETB, and SETC, that are 
discussed under SET Symbols , and AIF, AGO, 
ACTR, and ANOP that are discussed in this 
section. 



AIF — Conditional Branch 



The AIF instruction alters conditionally 
the sequence in which source program 
statements are processed by the assembler. 
The conditional branch is located within or 
outside of the macro definition. If the 
logical expression in the operand field is 
true, the macro generator branches to the 
sequence symbol following the logical 
expression. Figure 3.23 illustrates the 
typical form of this instruction. 



r r~ r 1 

| Name | Operation | Operand | 

| A sequence | AIF |A logical expression 

j symbol or | | enclosed in paren- 

jnot used j | theses, immediately 

j j | followed by a 

j j | sequence symbol. 

L 4. L 



Figure 3.23. 



Conditional Branch 
Instruction 



The following are valid operands of AIF 
instructions : 

( 6AREA+X • 2D ' GT 29). READER 

UNAME+FIVE GT 2). POSSIBLE 

The following are invalid operands of 
AIF instructions: 



(T'&ABC NE T'fiXYZ) 



No sequence symbol 



(T'SABC NE T*SXYZ).X4F2 

Blank between 
logical expression 
and sequence symbol 



.X4F2 



No logical expression 
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AGO — Unconditional Branch 



The AGO instruction causes an unconditional 
branch to the sequence symbol in the 
operand. Figure 3.24 illustrates the 
typical form of this instruction. 

| Name j Operation j Operand | 

|A sequence | AGO |A sequence symbol | 
| symbol or j | | 

| not used | j | 

l j. x j 



Figure 3.24. 



Unconditional Branch 
Instruction 



The statement named by the sequence 
symbol in the operand is the next statement 
processed by the assembler. The statement 
named by the sequence symbol may precede or 
follow the AGO instruction. 



to be branched to. Figure 3.25 illustrates 
the typical form of this instruction. 



r t t 1 

| Name | Operation | Operand , | 

|. 1. + j 

| A sequence | ANOP |Not used, must not | 
| symbol j jbe present. j 



Figure 3.25. 



Assembly No Operation 
Instruction 



If the programmer wants to use an AIF or 
AGO instruction and has already entered a 
symbol or variable symbol in the name entry 
of the statement to which he wishes ito 
branch, he cannot place a sequence symbol 
in the name entry. An ANOP instruction can 
be placed before that instruction, and then 
branched to. This has the same effect as 
branching to the statement immediately 
after the ANOP statement. 



ACTR — Conditional Assembly Loop Counter 



The ACTR limits the number of AGO and AIF 
branches executed within a macro 
definition. When used, the ACTR must 
appear after the globals and locals symbol 
definition statements and before any other 
type of model statement. The ACTR 
instruction assigns a maximum count to the 
number of AGO and AIF branches executed 
within the macro definition. When the 
count reaches zero, an END card is 
generated. If the count is zero before 
decrementing, the assembler takes one of 
two actions: 

1. If a macro definition is being 
processed, the processing of it and 
any nested macros above it is 
terminated, and the next statement in 
the main portion of the program is 
processed. 

2. If the main portion of the program is 
being processed, conditional assembly 
is terminated, and the portion of the 
program generated so far is assembled. 
If an ACTR statement is not given, the 
assumed value of the counter is 150. 



EXTENDED CAPABILITIES 



The macro language provides additional 
features that allows the system to: 



1. Terminate processing of macro 
definition 

2. Generate error messages 

3. Define global SET symbols (discussed 
in the section SET Symbols ) 

4. Use system variable symbols (discussed 
under System Variable Symbols ) 

5. Prepare keyword and mixed-mode macro 
definitions and write keyword and 
mixed-mode macro instructions 
(discussed under Macro Instruction 
Formats) 



MEXIT — Macro Definition Exit 



ANOP — Assembly No Operation 



The ANOP instruction facilitates branching 
to a statement that has a symbol or 
variable symbol in the name field. The 
ANOP instruction causes no operation and is 
inserted immediately before the statement 



The MEXIT instruction allows exit from the 
macro definition at various points in the 
definition. However, when this instruction 
terminates the macro definition, it does 
not signify the physical end of the 
definition. Figure 3.26 illustrates the 
typical form of the instruction. 
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r t- — t ~ 1 

| Name | Operation j Operand | 

| A sequence | MEXIT |Not used, must not | 
| symbol or j jbe present. j 
| not used j j j 

l x x . J 



Figure 3.26. 



Macro Definition Exit 
Instruction 



MEXIT should not be confused with MEND. 
MEND indicates the physical end of the 
macro definition. MEND must be the last 
statement of every macro definition, 
including those that contain one or more 
MEXIT instructions. 



MNOTE Statement 



The operand entry of the MNOTE 
instruction may be written in one of the 
following forms: 

1 . severity code , • message • 

2. , 'message' 

3. 'message* 

For two and three, the severity code is 
assumed as one. 

The MNOTE statement appears in the 
listing with a statement number at the 
point where it was generated. Because the 
message portion of the MNOTE operand is 
enclosed in apostrophes, two apostrophes 
must be used to represent a single 
apostrophe. Two ampersands must be used to 
represent a single ampersand that is not 
part of a variable symbol (see Figure 
3.28). 



The MNOTE instruction may generate a 
message and indicate the level of severity 
of the error. The severity code is for the 
programmer's information only and is not 
used by the DOS assembler or control 
program. This instruction requests a 
message to be printed on the output 
listing. Figure 3.27 illustrates the 
typical form of this instruction. 

r t t n 

J Name | Operation | Operand | 

j. x x j 

| A sequence | MNOTE |See examples in text| 
I symbol or j j | 

| not used j j j 

l _ x x J 

Figure 3.27. MNOTE Instruction 



j Name j Opera- j Operand j 

I Ition | | 

| | MNOTE | 1,' ERROR**— NOT RECOVERABLE' | 

Figure 3.28. Sample MNOTE 

Figures 3.29 and 3.30 are examples of 
macro writing and usage. Figure 3.29 
defines the MSG macro. There are no 
locally defined symbols. All are globals. 
Figure 3,30 is an example using the MSG 
macro to write an appropriate message 
pertaining to a particular step of the 
routine. The generated coding of the MSG 
macro is indicated by a '♦' after the 
statement number. 
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PAGE 1 


STMT 


SOURCE 


STATEMENT 




DOS CL3-4 06/09/69 


1 




MACRO 




MSG00010 


2 


SNAME 


MSG 


&A,SB 


MSG00020 


3 




GBLA 


&MSGLTH PROTOTYPE 




4 




GBLC 


&LATBR 


MSG00030 


5 




GBLB 


SREPGLB, &MSGGLB 


MSG00040 


6 




AIF 


O&A' EQ •'). BADMSG 


MSG00050 


7 




AIF 


C'SB' EQ 'REPLY'). SETREP 


MSG00060 


8 




AIF 


('SB' EQ ' '). INORDER 


MSG00070 


9 




MNOTE 


1,' INVALID REPLY OPERAND, I QUIT' 


MSG00080 


10 




MEXIT 




MSG00090 


11 


.BADMSG 


MNOTE 


1,'NO MESSAGE CODED, I QUIT' 




12 




MEXIT 




MSG00110 


13 


.SETREP 


ANOP 




MSG00120 


14 


SREPGLB 


SETB 


1 


MSG00130 


15 




AGO 


.BEGIN 


MSG00140 


16 


. INORDER 


ANOP 




MSG00150 


17 


SREPGLB 


SETB 





MSG00160 


18 


.BEGIN 


ANOP 




MSG00170 


19 


JC 


MSG MACRO 


CHANGE LEVEL 2-0 




20 


&NAME 


L 


15,=V(MSGRTN) 




21 




AIF 


(SREPGLB). B 




22 




BAL 


14,4(15) NON-REPLY HANDLER 




23 


.C 


ANOP 






24 


SMSGLTH 


SETA 


K'SA-2 




25 




DC 


FLl'SMSGLTH. ' MESSAGE LENGTH 




26 




DC 


CSA MESSAGE 




27 




AIF 


(NOT SREPGLB). D 




28 


SNAME. A 


DC 


C ' ANSWER BYTE 




29 


.D 


ANOP 






30 




DS 


OH RESTORE BOUNDARY 




31 




MEXIT 






32 


.B 


BAL 


14,0(15) REPLY HANDLER 




33 




AGO 


.C 




34 




MEND 







Figure 3.29. Sample MSG Macro 



Section 3: Program Design 185 



STMT 

1176 
1177 
1178 
1179 
1180 
1181 
1182 
1183 
1184 
1185 
1186 
1187 
1188 



SOURCE STATEMENT 



DOS CL3-4 



THE FOLLOWING ROUTINE CHECKS THE RETURN CODE AFTER A 
READ, WRITE, CONTROL COMMAND IS GIVEN 

REGISTER EIGHT CONTAINS THE ADDRESS OF ROUTINE WHICH 
JUST GAVE THE READ OR WRITE COMMAND. IF THE COMPLETION 
IS BAD REG 8 IS USED TO TURN THIS DEVICE OFF (NO MORE 
OPERATIONS WILL OCCUR ON THIS DEVICE), THE OPERATOR MUST 
RELOAD THE PROGRAM INORDER TO RESTART THIS DEVICE 



1190 CKCONDC 


LTR 


1191 


BNZ 


1192 


BR 


1193 CONTCK 


MSG 


11 94+" 




1195+CONTCK 


L 


1196 + 


BAL 


1197 + 


DC 


1198 + 


DC 


1199 + 


DC 


1200 


LR 


1201 


BAL 


1202 


STC 


1203 


LR 


1204 


BAL 


1205 


STC 


1206 ERRMSG 


MSG 


1207+" 




1208+ERRMSG 


L 


1209 + 


BAL 


1210 + 


DC 


1211 + 


DC 


1212 + 


DS 


1213 X 


MVC 


121+ MSG2 


MSG 


1215+" 




1216+MSG2 


L 


1217 + 


BAL 


1218 + 


DC 


1219 + 


DC 


1220 + 


DS 


1221 PDUMP 


PDUM 


1222+" 360N- 


CL-453 







RF,RF 

CONTCK 

R2 

•ERROR OCCURRED ON CKI 

MSG MACRO CHANGE LEVEL 
15,=V(MSGRTN) 
14,4(15) NON-REPLY HAN 
FLl'35' MESSAGE LENGTH 
C ERROR OCCURRED ON CK 
OH RESTORE BOUNDARY 
R3,RF 
R2, FORMAT 
R3,ERRMSG+28 
R3,RF 
R2,FORMATl 
R3,ERRMSG+27 
'CONDITION CODE = 

MSG MACRO CHANGE LEVEL 
15,=V(MSGRTN) 
14,4(15) NON-REPLY HAN 
FLl'21' MESSAGE LENGTH 
C'CONDITION CODE = 
OH RESTORE BOUNDARY 
MSG2+27(7),OPERATIN 
'LAST OPERATION - 

MSG MACRO CHANGE LEVEL 
15,=V(MSGRTN) 
14,4(15) NON-REPLY HAN 
FLl'36* MESSAGE LENGTH 
C'LAST OPERATION - 
OH RESTORE BOUNDARY 
3 START, END 

PDUMP CHANGE LEVEL 3 



CK CONDITION CODE 

EXIT BACK CK GOOD 
NG RETURN CODE' 
2-0 

DLER 

ING RETURN CODE' MESSAGE 

SWITCH REGS 

GO FORMAT CONDITION CODE 

INSERT CHAR 

GO FORMAT SECOND CHAR 

INSERT SECOND CHAR 
i 

2-0 
DLER 
' MESSAGE 



2-0 
DLER 

' MESSAGE 



-0 



Figure 3.30. Sample MSG Coding 
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This section presents debugging aids 
considered helpful to both the application 
and system programmer. Information 
contained in this section includes: 

• System action on all cancel conditions 

• Register conventions for following 
program flow 

• When a storage print is useful 

• The types of documentation used in 
locating program problems 

• The action taken when a hard wait or 
unending loop is encountered 

• The importance of low-core messages and 
system error messages as an aid in 
determining a starting point for 
approaching a programming problem. 

Sample programs in COBOL, PL/I, FORTRAN, 
and RPG, together with their respective 
linkage editor maps to show how to locate 
programs and partition save areas in main 
storage are included. 



\ Gathering Documentation 



This is an explanation of the types of 
documentation useful in debugging problem 
programs. All SYSLOG and SYSLST error 
messages, program listings, the supervisor 
listing, linkage editor map, and a core 
dump should be gathered. 

A system dump of main storage should be 
available, but if the system is in a hard 
wait or an unending loop, a stand-alone 
(self-loading) dump will have to be taken. 



The DOS stand-alone dump generator, 
DUMPGEN, produces a stand-alone dump 
program tailored to system requirements. 
The dump can either be a conventional dump 
program or a formatting dump program. A 
DSERV of the core image library directory 
may be helpful when program checks occur in 
the logical transient area. The directory 
can be displayed by an alphamerically 
sorted listing of the directory entries, or 
a listing of the entries in the order they 
appear in the directory. 

The label cylinder display program 
(LSERV) can also be used for error 
analysis. LSERV displays the TLBL and the 
DLBL and EXTENT information contained on 
the SYSRES label cylinder. Information 
about secured data files is not displayed. 

DOS I/O error logging, MCRR (Machine 
Check Recording and Recovery) , RMS 
(Recovery Management Support) , and the DUMP 
option of job control are additional 
facilities for error analysis. The RMS 
consists of two functions: MCAR (Machine 
Check Analysis and Recording) , and CCH 
(Channel Check Handler) . 

Other facilities for error analysis are 
EREP (Environmental Recording, Editing, and 
Printing Program), ESTVUT and ESTVFMT 
(Error Statistics by Tape Volume Utility 
programs) . EREP edits and prints data that 
has been stored in the recorder file 
(SYSREC) by the I/O error logging and/or 
MCRR and/or MCAR/ CCH functions. For the 
IBM System/370, EREP creates and maintains 
a history tape, and, if specified at system 
generation time, RDE (Reliability Data 
Extractor) of OBR/MCAR/CCH and, if 
specified by the ROD command, IPL/EOD (End 
of Day) data. Figures 4.1, 4.2, and 4.3 
show the SDR communications region, the 
MCRR linkage table, and the RMS linkage 
area. 



> 
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SDR 
Flags 

(SDR- 
TABLE) 



1 

Parti 
tion 
ID 



Number 
of SDR 
Records 



10 



First SDR ID 
BBCCHHR 



17 



First OBR ID 
BBCCHHR 



24 



Current OBR ID 
BBCCHHR 



25 



31 



Last OBR ID 
BBCCHHR 



32 35 

Address of 

SDR 

Accumulator 



36 39 

Address of 
SDR Unit 
Switches 



40 



43 



Reserved 



44 



71 



List Save Area 



72 



75 



76 



95 



Mask 
Bytes 



SDR1 Work Area 



96 



103 



Test Under 
Mask Table 



104 



107 



Temporary 
Work Area 



108 



111 



Test Under 

Mask 

Instruction 



112 115 

F'65536' 



116 117 

SDR Queue 
Save Area 



118 



135 



SDR2 Work Area 



136 



155 



Area Modified by A -Transients 



156 



159 



SDR Error 
Message 
Save Area 



160 



163 



Branch 
Instruction 



164 



167 



O BR/SDR 
Flag Byte 
Address 



168 



Data Area for OBR/SDR Records 



250 





Key 


to SDR Communications Region Displacements: 




Q 


SDR Flags: 






Bit 
1 

2 
3 


Key of OBR Bit 4: RF option = CREATE 
RDE option 5: RF option = YES 
Initial IPL time 6: Error while recording 
RF option = NO, recording is suppressed 7: Recorder file ready 






Set and tested by Job Control.. 




Q 


Set by EREP transient SSBSDRUP to identify the partition making the call for EREP recording. 

Settings: X'10' if EREP is running in BG. 
X'20 1 if EREP is running in F2. 
X'30' if EREP is running in Fl . 

X'01 ' with one of the above if recorder file is ready. 
X'00' with one of the above if recorder file is not ready. 







Initial number of SDR records specified. If SDR record count is not specified, the file is formatted for OBR records only 
(SJOBCTLM, see IPLand Job Control PLM, GY24-5086). 


Q 


Disk address of first SDR record. 




K 


Disk address of first OBR record . 






rjr 


Disk address of current OBR record . 






25 


Disk addr 


ess of last OBR record. 



Figure 4.1. SDR Communications Region (Part 1 of 2) 
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Key to SDR Communications Region Displacements: 



32 



36 



40 



44 



72 



76 



96 



104 



112 



116 



118 



136 



156 



160 



164 



168 



Address of SDR accumulator area which contains half -byte counters and accumulated error conditions. 

Address of SDR unit switches . 

SDR switch byte (1 for each PUB): 

X'80' - Update operations complete 

X'40 1 - Counters on external file overflowed 

X'20 1 - I/O error during write 

X'08 1 - SDR update half -byte counters routine required 

X'04 1 - Update SDR record routine required 

Other - Reserved 

When entry contains X'01 000000', indicates MCRR, no SDR supported. 

Reserved . 

SDR1 register save area . 

Mask formats for interpretive error accumulator, SDR1 : 

X'FF' - End of update 

X'FE' - Bypass counter 

X'FD' - Set up 'OR' condition to previous counter 

X'FO - Ignore list item 

Other - Test bit in error queue 

Used by the interpretive error accumulator routine to process list passed by OBR/SDR A -transient. 

Used by the interpretive error accumulator routine. 

Used by the interpretive error accumulator routine for address alignment. 

Executed by the interpretive error accumulator routine. 

Loop counter for the SDR counter update. 

Save area for pointers to entries in the SDR error queue. 

Work area where half byte error counters are unpacked and updated . 

List of devices passed to the SDR processor from $$ANERAD . 

Used by SDR/OBR recorder phases to pass error message displacements and disk error addresses in event of an error. 

Entry point from OBR/SDR A -transients. Branches to label SDRMM. 

Pointer into the OBR/SDR unit switches. Status posted by recorder phases. (See byte 36). 

OBR and SDR records formatted by the recorder phases. 



Figure 4.1. SDR Communications Region (Part 2 of 2) 
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MCRRPSW1 (See Note) 



(Hexadecimal Displacement) 
(Decimal Displacement) 


8 
8 


10 
16 


14 
20 


MCRR I PSW 

Reentrant 
■ Address of 
J MCRR Routine 

I 


MCRR PSW 

| Address of 
1 MCRR Routine 


Address of 
Channel 
Failure 
Routine 


Address of 
Machine 
Check 
Routine 


xxxxxxxx 


XXXXXXXX 


XXXX 


XXXX 



Key to displacement: 

Machine Check Recording and Recovery PSW. Loaded to enable machine check interrupts. Second word (displacement 4-7) 
contains reentrant address (MCRETURN) to MCRR routine. 

8 Machine Check Recording and Recovery PSW. Loaded to enable machine check interrupts. Second word (displacement 12-15) 
contains initial address (MCRRRTN) of the MCRR routine. 

16 Address of channel failure routine (MACHEK1). 

20 Address of machine check routine (MACHEK). 

Note: MCRRPSW1 is the label of the first byte of the MCRR Linkage Table. 



Figure H.2. Machine Check Recording and Recovery (MCRR) Linkage Tabl< 
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RASLINK 

(Decimal Displacement) 

CPUID 


8 
RASDMC 


9 
RASFLAGS 


10 

MC FLAGS 


11 
RASMODEL 


12 
RASTABA 


16 
RASBASE 


CPU ID field 


Damaged 

Channel 

byte 


RAS flag 
byte 


Machine 

Check 

flags 


CPU 
Model 


RAS Table 
(RASTAB) 
address 


Base address 
for RAS 
Monitor 


XXXXXXXX 


X 


X 


X 


X 


XXXX 


XXXX 



Key to RAS Linkage Area displacements: 
CPU ID field. 
Address of damaged channel, or X'FF 1 if no channel damaged. 







10 



11 



12 



16 



RAS Flag byte: 



bit 


1 
2 
3 
4 
5 
6 
7 



Machine Check Flags: bit 



flag 

X'80' 
X'40' 
X'20' 
X'10' 
X'08' 
X'04' 
X'02' 
X'OT 

flag 



description 

RAS active 

RAS SIO flag 

RTA in control 

RAS I/O delayed 

Channel check on error SIO 

Reserved 

Channel check on SIO 

I/O active for SIO 

description 



0-4 




Reserved 


5 


X'04' 


Hard machine check 


6 


X'02' 


All machine records built 


7 


X'OT 


All channel check records built 



Largest CPU Model. 

Address of RAS Table (RASTAB). 

Address used for base register in RAS Monitor Program. 



I Figure 4.3. RMS Linkage Area (RASLINK) 
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Further documentation can be obtained by 
executing the PDAID program, which records 
(traces) certain events and either writes 
them on the I/O device specified or 
maintains thera in the CE area (or alternate 
address area). The program can trace: 

1. fetching or loading of programs or 
phases (Fetch/Load Trace) . 

2. input/output activity (I/O Trace). 

3. supervisor calls (GSVC Trace). 

4. QTAM input/output activity (QTAM 
Trace) . 

The On-Line Test Executive Program 
(OLTEP) , together with the On-Line Tests 
(OLTS) , make up the On-Line Test System, 
which tests I/O devices with minimum 
interference to other programs running on 
the system. RETAIN/370 is an OLTEP 
function that allows the OLTEP programs to 
be executed on the System/ 370 from a remote 
location. RETAIN/370 is yet another 
problem determination tool. See the DOS 
OLTEP listed in the Preface for a detailed 
description. 

The facilities mentioned form the DOS 
problem determination aids. Problem 
determination is a process or a procedure 
for' determining the cause of an error. The 
DOS Messages listed in the Preface 
recommends a specific procedure to follow 
when an error condition occurs; the DOS 
System Control and Service gives a detailed 
explanation of problem determination aids. 

Error messages are very important and 
can supply useful information in 
determining where to start looking for the 



trouble (i.e., in what partition the 
failure took place) . A message number or 
code is supplied to give further 
information about the error. The program 
check message gives the location of the 
failing operation code and the condition 
code from the program status word (PSW) . 
This gives you a starting point for 
reconstructing the cause of the error. 



The program listing is an extremely 
useful tool in determining if the error 
condition was caused by a logic error or a 
particular condition that you had not 
considered when the program was written. 

The supervisor (SUPVR) listing allows 
you to check facts at the time of failure 
and to determine if the error indications 
were valid. The listing and the main 
storage dump allow you to locate the 
Program Interrupt Key (PIK) to determine 
the task in control of the system at the 
time of failure. 

By locating the Program Information 
Block (PIB) table, you can easily locate 
programs in main storage. See Figures 4.4, 
4.5, and 4.6 for a description of the PIB 
table. Using the information in the PIB 
table, you can check the cancel code and 
find the partition save area address. The 
partition save area supplies you with such 
useful information as the PSW and register 
values that you can use to locate the last 
instruction executed. 

The system communications region (Figure 
1.7) within the supervisor contains the 
address of the PIB table, and other useful 
information for determining the nature of 
the error. 
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PIB TABLE 



Byte 
Number 



10 



12 



13 



14 



15 



= 16 
Byte 
Length 



All 

Bound 

PIB 



Flag 
Byte 
See A 



Reserved 



SP Prefrx 



Branch Instruction to the 
All Bound Routine 



Reserved 




Flag 
Byte 
See B 



Cancel 
Code 



SYSLOG ID 
(BG, F2, or Fl) 



NOP 

Instruct- 
ion 
(CR) 



Address of the 
Partition Save Area 



Number 

of Core 

Blocks 

(Note 2) 



Address of the Origin 
of the Partition 



PIB 
Assign 

Flag 
See D 



User 

LUB 

Index 



Number 

of 
Program 

LUBs 



Flag 
Byte 
SeeC 



Attention 
PIB 



Flag 
Byte 
See E 



Cancel 
Code 



SYSLOG ID 

(AR) 



Branch 
Code 

(BC) 



Active=Address of 
Save Area 

Inactive = Remainder of 
BC Instruction 



Switch 

Byte 

See F 



Logical Transient Bucket 
(contains save 
area address) 



X'07' 
See D 



Address of 

the Logical 

Transient 



Quiesce 
PIB 



Flag 
Byte 
See A 



Cancel 
Code 



C'/oV 



Branch Instruction to 
Quiesce I/O Routine 



Scratch 

Byte 
X'00' 



Channel PUB Table Index Values 



X'00 1 



X'04' 



X'08' 



X'OO 



X'10' 



X'14' 



X'18' 



Supervisor! 
PIB 



Flag 
Byte 
See A 



Cancel 
Code 



SP Prefix 



Branch Instruction to 
General Exit Routine 



Address of 
SYSRES PUB 



Length of Error 
Queue Entry 



Constants to Clear Bytes 
2-5 of CCB 



X'lF' 



X'05' 



X'00' 



X'00' 



Flag 
Byte 
See B 



Cancel 
Code 



SYSLOG ID 
(BG, F2, or Fl) 



NOP 
Instruc- 
tion 



Address of the 
Save Area 



Number 
of Core 
Blocks 
(Note 2) 



Address of the 
Origin of the 
Main Task 



PIB 
Assign 

Flag 
SeeD 



User 
LUB 
Index 



Number 

of 
LUBs 



Flag 
Byte 
SeeC 



{Background PIB 
Forearound 2 PIB 
Foreground 1 PIB 
When a batch-only environment is established at generation time, the All Bound and Foreground PIBs are excluded from the table, and only 
one (BG) problem program PIB is built. However, the X'20' bytes that F2 and Fl PIBs normally occupy (between PIBBG and PIBAR) are 
filled with 32 bytes of DIBs data. 

Note 2: Number is in multiples of 2K for F2 and Fl . BG is always 10K (X* 0A'). 

Note 3: Total of nine subtask PIBs are generated, and only when AP is specified at generation time. 

* See Figure 4.5 for flag byte expansions A, B, C, D, E and F. 

Bytes 90 and 91 (X'5A" - '5B') of the communications region contain the address of the first part of the PIB Table. Label PIBTAB identifies the first 
byte of the table. 

Figure 4.4. First Part of Program Information Block (PIB) Table 
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A Supervisor, Quiesce, and ALL Bound PIB Flags: 


D PIB Assign Flag 


Bit 


1 = Always one 


X'80' = SYSRES DASD file protect inhibited (allow write 


1-4 


= Always zero 


operation on SYSRES) 


5 


1 = Always one 


X'40 1 = Channel appendage exit allowed (BTAM) 


6 


1 = Active 


X'20' = Cancel in progress (used in terminator function) 




= Inactive 


X' 10' = Cancel control (set on a foreground cancel) 


7 


1 = Active 


X'08' = Hold-Release flag for foreground assignments 




= Inactive 


X'07' = Supervisor or Attention routine PIB assign flag setting 
X'04' = Background program PIB assign flag setting 


Note 


: If PTO = YES is specified, Bit 6 is a one in the 


X'02 1 = Foreground 1 program PIB assign flag setting 




Quiesce I/O PIB when attached by the super- 


X'OV = Foreground 2 program PIB assign flag setting 




visor. Otherwise it is always zero. 


E Attention PIB Flag 


B 


Problem 


Program PIB Flag (First Byte in PIB): 








Bit 0: 1 = Registers stored 






Bit 


1 = Registers stored 


= Registers not stored 




= Registers not stored 


1-5 : = Always zero 


1-3 


= Always zero 


6 : 1 = Attention routine active 


4 


1 = QTAM Wait active 


= Attention routine SVC 2-bound 




= QTAM Wait inactive 


7 : 1 = Active 


5 


= Normal execution 

1 = Program has seized the system 


= SVC 7-bound 


6 


1 = Unbound 


X'80 1 indicates the attention routine is not present in the system. 




= SVC 2-bound (B-transient in progress) 


X'89' indicates the program is IDRA bound 


7 


1 = Unbound 


1 1 




= SVC 7-bound (waiting for an I/O interrupt) 


F Attention PIB Switch Byte 


X'80 


' indicates the program is not present in the system 


1 1 


X'87 


1 indicates the program is PTO bound 


Bit 0-2: Reserved 


X'89 
1 1 


indicates the program is IDRA bound 


3: 1 = PTAFTCH (Fetch $$ANERRY, Z, or 0) Switch ON 
= PTAFTCH (Fetch $$ANERRY, Z, or 0) Switch OFF 


C Problem 


Program PIB Flag (Last Byte in PIB): 


4: 1 = Detach Logical Attention Routine ($$BATTNA) 
Switch ON 


BitO 


1 = Batched Job in Foreground 


= Detach Logical Attention Routine ($$BATTNA) 




= No BJF . 


Switch OFF 


1 


: Cancel in LTA and Device not Assigned 


5: 1 = Physical Attention Recall Switch ON 


2 


: 1 =/&on SYSIN if DASD • 


0= Physical Attention Recall Switch OFF 




0= No/&on SYS IN 


6: 1 = Attention Request Switch ON 


3-4 


: Reserved 


= Attention Request Switch OFF 


5 


: 1 = Task is cancelled 


7: 1 = External Interrupt Request Switch ON 




= Task not cancelling 


= External Interrupt Request Switch OFF 


6 


: 1 = Subtask (s) attached 
= No subtasks attached 




7 


: 1 = In AB Routine 
- Not in AB Routine 





Figure 4.5. PIB Flag Expansions 
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Byte 







1 


2 


3 


4 


, 


U 


7 


8 


9 


10 


11 


12 


13 


14 


15 


Number 


~ 


















































H'16' 










H'O" 




















Priority of 










All Bound 






All Bound 








Reserved 






All Bound 




Reserved 




PIB 


Reserved 


PIB 


~ 














PIB 










Displacement 






















(Lowest) 


















Background 
PIB 


? 


Address of 
BG Comm. 
Reg ion 


Syst 
LUBI 


em 
ndex 


Reserved 


1 

Priority of 
BGPIB 


Address of Termination 
ECB, if any, or F'O' 


X'0010' 

BGPIB 

Displacement 


Reserved 


















(Note 4) 










I 






FG2 




Addr 


3SS Of 


Syst 
LUBI 


em 






1 

Priority of 
F2 PIB 


Addr 


ess of Termination 


X'0020' 






PIB 


./ 


Area Comm. 
Region 


ndex 


Rese 


rved 


ECB, if any, or F'O 1 


F2 PIB 
Displacement 


Reserved 


(Note 1) 




(Note 2) 










(Note 4) 






















1 
Address of 










1 










X'OOSO' 






FG1 
PIB 


«f 


Area Comm. 
Region 


System 
LUB Index 


Reu 


tved 


Priority of 
Fl PIB 


Address of Termination 
ECB, if any, or F'O' 


Fl PIB 
Displacement 


Reserved 


(Note 1) 




(Note 2) 










(Note 4) 






















1 

Address of 










1 
H'3' 










X'0040' 






Attention 
PIB 


V 


BGC 

Reg 


„omm. 
ion 








Res* 


rved 


Priority of 

Attention 

PIB 

I 




F' 


0' 




Attention PIB 
Displacement 


Reserved 


Quiesce p!, 
I/O PIB 






Rese) 


^ved 






1 

H'2 1 

Pribrity of 

Quiesce 

I/O PIB 




F' 


0' 




x'ooso 1 

Quiesce PIB 
Displacement 

I 


Reserved 


















H'T 










1 
X'0060' 






Supervisor 
PIB 


A 

~7 






Rese 


•ved 






Priority of 
Supervisor 




F' 


0' 




Supervisor 
PIB 


Reserved 




r 














PIB 










Displacement 






















(Highest) 










1 






Subtask 




Addr 


ess of 


Sys 


tern 


Rex 


srved 


1 

Priority of 


E 


CB Adc 


dress for 




PIB 
Displacement 


Reserved 


PIB 




Region 


LUB Index 






Subtask 


Subtask, or rU" 


of Ma in task 






(Note 3) 




1 


| 






(Note 4) 




1 




| 







= 16 
Byte 
Length 



Note 1. Generated only if MPS is specified. 

Note 2.. Always background communications region except when MPS = BJF. 

Note 3. Total of nine subtasks generated, and only when AP is specified. 

Note 4. Will be filled in with halfword indicating the relative priority of task in the system (range H'4' to H'15', the lower 
number the higher the priority). 

Bytes 124 and 125 (XVC'-VD') of the communications region contain the address of the second part of the PIB table. Label 
PIB2AD identifies the first byte of the table. The second part of PIB table comes before the first part in storage allocation. 

Figure 4.6. Second Part of Program Information Block (PIB) Table 



the 
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SYSTEM ACTION UNDER CANCEL 



The following lists all cancel codes and 
their message prefixes. Some do not appear 
in a foreground PIB, such as the X'FF' code 
(supervisor catalog failure) . This type of 
function can be performed only in the 
background partition. The linkage editor 
and system maintenance functions must also 
be performed in the background area. 

Byte one of the PIB table contains a 
cancel code stored by the system any time a 
cancel condition is encountered. The PIB 
table can be located by displaying on the 
console the communication region address 
(located at X , 16 , -X , 17 l ) plus the 
displacement of a X'SA* and X'SB 1 . This is 
the address of the first part of the PIB 
table. Remember each entry is 16 decimal 
(X^O 1 ) bytes in length. Each byte of the 
PIB is numbered starting with and 
continuing through 15. The layout of the 
PIB table and the communications region can 
be found in Figures 4.4-1.6 and Figure 1.7. 

Cancel Code (Hexadecimal) : 10 

Message Code ; None 

Description^ Action or Condition ; This is 
normal end of job (EOJ) . Cancel code X'10 1 
is posted in byte 1 of the PIB for the 
program issuing the SVC 14. The next time 
the' canceled program is selected on general 
exit, an SVC 2 is taken to call in a 
B-transient program, which, in turn, cajds 
job control to perform the end-of-job step. 



Cancel Code (Hexadecimal) ; 17 

Message Code ; 0S02I 

Description, Action or Condition ; This is 
caused by the main task in a partition 
issuing the CANCEL macro without detaching 
all subtasks running under its control. 



Cancel Code (Hexadecimal) ; 18 

Message Code ; None 

Description, Action or Condition ; This is 
caused by the main task issuing the DUMP 
macro with subtasks attached. It allows 
the dump to take place without the error 
cancel message being printed. All subtasks 



are detached and EOJ is taken after the 
dump is complete. 



Cancel Code (Hexadecimal) ; 19 

Message Code ; 0P74I 

Description, Action or Condition ; This is 
caused by the operator responding to an I/O 
error message with the cancel option on the 
1052. 



Cancel Code (Hexadecimal) ; 1A 

Message Code ; 0P73I 

Description. Action or Condition ; This is 
caused by an I/O error that cannot be 
handled by the program (task) , thus causing 
the program to be canceled. If the DUMP 
option is specified at system generation 
time, a dump of the supervisor and the 
partition in which the program was running 
will be taken. 



Cancel Code (Hexadecimal) 
Message Code ; 0P82I 



IB 



Description, Action or Condition ; This is 
caused by a channel failure. 



Cancel Code (Hexadecimal) ; 1C 

Message Code ; 0S14I 

Description, Action or Condition ; This is 
caused by a subtask issuing the CANCEL ALL 
macro. This causes all other subtasks to 
be detached and canceled. The main task is 
canceled, and a dump of the supervisor and 
partition involved results. 



Cancel Code (Hexadecimal) ; ID 

Message Code ; 0S12I 

Description, Action or Condition ; This is 
caused when the main task terminates before 
all subtasks have been detached. This 
indicates the subtasks were canceled before 
they came to a normal EOJ. The subtasks 
are detached, and the complete partition is 
canceled. 
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Cancel Code (Hexadecimal) ; IE 

Message Code ; 0S13I 

Description, Action or Condition ; This is 
caused by the combination of one task 
issuing an enqueue for a resource, and 
another task issuing a dequeue for that 
same resource. As a result, the previous 
owner cannot be identified because register 
in the save area has been modified. 

Cancel Code (Hesadecimal) ; IF 

Message Code ; 0P81I 

Description, Action or Condition ; This is 
caused by a CPU failure. 



Cancel Code (Hexadecimal) ; 20 

Message Code ; 0S03I or 0S11I 

Description. Action or Condition ; This is 
caused by a program check interrupt. The 
program is canceled by the system. The 
user may supply a PC or AB routine to 
handle this condition via the STXIT macro. 
This code is also used when a routine in 
the transient area is canceled due to a 
program check in the task or subtask using 
it. 



Cancel Code (Hexadecimal) ; 21 
Message Code ; 0S04I or 0S09I 

Description. Action or Condition ; This can 

I be caused by many user errors. See Figure 
4.7 for a list of the causes. 



Cancel Code (Hexadecimal) ; 22 

Message Code ; 0S05I or 0S06I 

Description, Action or Condition ; This is 
caused by the issuing of a FETCH (SVC 1) or 
a LOAD (SVC 4) macro whose phase name 
cannot be found. This cancel code is also 
used when a logical transient is canceled. 



Cancel Code (Hexadecimal) ; 23 
Message Code ; 0S02I 



program or task, the program or partition 
is canceled. If issued by a subtask, the 
subtask only is canceled. 



Cancel Code (Hexadecimal); 2H 



Message Code ; 0S01I 



Description. Action or Condition ; This is 
a result of an operator entering CANCEL 
from the 1052. 



Cancel Code (Hexadecimal) 
Message Code ; 0P77I 



25 



Description. Action or Condition ; This 
caused by a program, task or subtask 
issuing a CANCEL macro. If issued by a 



is 



Description, Action or Condition ; This is 
a result of attempting to load a problem 
program phase at an address outside main 
storage or outside the requester's area 
(background or foreground) . This condition 
also occurs: 

1. if the program requires more main 
storage than is allocated to the 
partition where the program is to run 
or 

2. if an improper address is detected on 
an SVC interrupt (i.e., CCW address in 
CCB is invalid). 



Cancel Code (Hexadecimal) : 26 

Message Code ; 0P71I 

Description. Action or Condition ; This is 
a result of a program issuing an I/O 
request for a logical unit that is not 
assigned to a device. If a dump is taken, 
general register 1 contains the address of 
the CCB. If the CCB is unavailable, the 
logical unit message contains SYSxxx. 



Cancel Code (Hexadecimal) : 27 

Message Code : 0P70I 

Description. Action or Condition : This is 
a result of a program issuing an I/O 
request for a logical unit for which there 
is no logical unit block (LUB) entry 
(invalid LUB code in CCB). If a dump is 
taken, general register 1 contains the 
address of the CCB. 



Section **: Debugging Aids 199 



The complete text for message 0S041 is: 

ILLEGAL SVC - HEX LOCATION nnnnnn - SVC 
CODE nn 

where nn is in hexadecimal notation. 

This message results from the following causes: 

1 . When nn is 02: The phase name given does not start 
with $$B, or 

For LIOCS, macros called in invalid sequence. As a 
result, an SVC 8 is issued after an SVC 2 before an 
SVC 9 has been issued to free the transient area, or 

For other conditions, the user specified a temporary 
exit (SVC 8) for a logical transient. In the temporary 
exit routine, another routine is called (by an SVC 2) 
before an SVC 9 is issued to free the transient area. 

2. When nn is 05: The 'to' range specified in the MVCOM 
macro is invalid, or 

MVCOM macro was issued by a foreground program, 
operating under single program initiation. 

3. When nn is 0A, 12, 13, or 18: The interval timer was 
not allocated to this partition, or 

The supervisor was generated without the timer option. 

4. When nn is OB: The call was not given by a logical 
transient routine. 

5. When nn is 16, 17, or 1A: The caller did not have a 
PSW key of zero. This is applicable only in a 
multiprogramming system. 

6. When nn is 23: More than 16 holds have been issued 
for the same track. 

7. When nn is 24: Free a non - DASD or a track that is 
not held. 

8. When nn is 26: A subtask issued attach, or the save 
area is not on a doubleword boundary. 

9. When nn is 27: A main task issued detach without 
SAVE = parameter, or 

A main task issued detach, but the ID of the subtask in 
the save area passed is not valid, or 

If a main task attempts to detach an already terminating 
subtask. 



10. When nn is 29: A DEQ is issued by a task that did not 
ENQ the resource. (This is valid in an AB routine.) 

11. When nn is 2A : A subtask (without an ECB = parameter) 
has issued an ENQ macro, or 

A subtask has issued an ENQ macro to a resource that 
has not been dequeued by another task that has been 
terminated, or 

A task has issued two ENQ macros to the same resource 
without an intervening DEQ. 

12. When nn is 2D: Emulator execution was attempted, 
but the EU parameter of the SUPVR macro was 
omitted or incorrectly specified during system 
generation. 

13. When nn is 32: For LIOCS: 

a. An imperative macro (such as WRITE or PUT) was 
issued to a module that does not contain the 
requested function, or 

b. A PUT was issued for an ISAM retrieve module 
without a preceding GET, or 

c. An invalid ASA first character for the printer 
was used, or 

d. A wrong length record indication occurred while 
processing 1287 documents when 
RECFORM=UNDEF, or 

e. The 1287 program erroneously contained a CCW(s) 
with the SLI flag bit 'OFF', or 

For COBOL, a wrong length record was detected in 
the object program. 

14. When nn is any other value: The supervisor function 
requested by the operand of the SVC is not defined 
for the supervisor being used. 



I Figure 4.7. Causes for Message 0S04I (Cancel Code X'21?) 
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Cancel Code (Hexadecimal) : 28 



Message Code ; None 

Description, Action or Condition : (QTAM 
cancel in progress) 



Cancel Code (Hexadecimal) 



Message Code; 0P72I 



30 



Description. Action or Condition ; This is 
a result of a program ignoring the reading 
of the /£ statement on SYSRDR or SYSIPT. 



Description. Action or Condition : This 
occurred when an IBM-supplied component 
failed to post a valid cancel code. 



All of these cancel codes cancel the 
program, task, or subtask when they occur. 
If multitasking is being used and a main 
task is canceled, all of the subtasks 
attached are detached and canceled as a 
result of the main task being canceled, 
with the exception of cancel code X'23*. 
If a dump option was specified at system 
generation time, the contents of the 
supervisor and the partition in which the 
cancel condition occurred is written on 
SYSLST. 



Cancel Code (Hexadecimal) ; 31 

Message Code : 0P75I 

Description. Action or Condition : This is 
a result of the number of pending I/O 
errors exceeding supervisor capacity. 

Cancel Code (Hexadecimal) : 32 

Message Code : 0P76I 

Description, Action or Condition : This is 
caused by DASD file-protect limits being 
exceeded or by an incorrect record 
reference for system files on disk. It 
will also be posted for unrecoverable I/O 
errors on tape. 



Cancel Code (Hexadecimal) : 33 

Message Code : 0P79I 

Description. Action or Condition : This 
occurs when a DASD command chain in a 
file-protected environment does not start 
with a command code of X'07*. This code 
indicates a long seek and must be the first 
command in the chain. 



Cancel Code (Hexadecimal) : 34 

Message Code : 0P84I 

Description. Action or Condition ; This is 
caused by an unrecoverable I/O error during 
a FETCH of a non-$ phase, thus resulting in 
the job being canceled. 



Cancel Code (Hexadecimal): FF 



Message Code : 0P78I 



The linkage editor map can be a great 
help in locating programs and subroutines 
that are included in the programs at object 
time. Common areas, load address, 
relocation factors, low-core and high-core 
addresses are also shown. In addition, the 
PHASE card is displayed to show where the 
phase was loaded (i.e., directly following 
the supervisor or at some other location) . 
This map is also helpful when working with 
multiphase programs. 



The system dump of main storage used 
with these items allows the programmer to 
relate all the information he has gathered 
to the contents of main storage at the time 
the error occurred. By using the dump and 
the listing, the programmer can see how his 
program appeared in main storage at the 
time of the error. By using the values 
found in the PIK and PIB table in the dump, 
he can see partition save areas, registers, 
and instructions to determine what actually 
caused the error. 



There are times when a system dump is 
not available to the programmer, such as 
hard waits and unending loops. When one of 
these conditions occurs, the only way to 
get a dump of main storage is to use a 
stand-alone dump. Remember that the 
address of the communication region (COMRG) 
is lost when a stand-alone dump is taken. 
Therefore, bytes X , 16 , -X , 17 t should be 
displayed before taking a dump of main 
storage to ensure that the programmer has 
the correct communication region address to 
use when he is analyzing the dump. If 
bytes X , 16 , -X , 17' are not displayed, the 
communications region start address can 
still be found by scanning the dump for the 
date in the form MM/DD/YY or DD/MM/YY (this 
indicates the start of COMRG) . Although 
the register values in a stand-alone dump 
(register print area of the dump) may not 
be valid, the partition save area values 
most likely will be valid. 
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Wait States 



The system is said to be in a wait state 
when the "wait" light is continuously lit 
and the "system" light is off. Wait states 
are divided into hard waits and soft waits. 

If the system is in a hard wait, the 
wait bit in the current PSW (bit 14) is set 
to one and the system mask is set to zeros, 
thus disabling all interrupts. Because no 
interrupts are allowed, a PSW swap cannot 
occur and the system must be re-IPLed to 
continue processing. 

A soft wait occurs when the DOS 
supervisor finds no in-core programs ready 
to run and loads a PSW with the wait bit 
set to one and the system mask set to all 
ones. The first interrupt returns control 
to the supervisor and processing may 
continue . 

A wait can easily be determined as hard 
or soft by causing an interrupt. If the 
system responds with some action, the wait 
is soft; if not, the wait is hard. The 
most convenient way for the operator to 
cause an interrupt is to press the 1052, 
3210, or 3215 request key. If the wait is 
soft, the attention routine responds with 
the "READY FOR COMMUNICATIONS" message. 



SOFT WAITS 



If the system is in a continuous soft wait, 
it is waiting for an interrupt to signal 
the completion of an event. Although the 
expected interrupt may be from the timer or 
external interrupt key, a missing 
device-end caused by hardware is the most 
frequent cause. The operator can make each 
device not-ready, then ready, to generate a 
device-end interrupt from each address. 
The system light flashes briefly as the 
supervisor examines and discards interrupts 
for which it was not waiting. The 
interrupt from the device waited for causes 
normal processing to continue. (The 
occurrence should be brought to the 



attention of the customer engineer as a 
possible hardware failure.) If this 
technique does not end the wait, take a 
stand-alone dump to find what the system 
was waiting for. 



HARD WAITS 



The DOS supervisor loads a hard-wait PSW 
when a failure occurs that puts the 
integrity of the control program or system 
data in doubt. The supervisor attempts to 
place a message in low core bytes 0-4. 
Figure 4.8 shows the explanation for each 
error. 

If a hard wait occurs, it is imperative 
that this message be retrieved and 
recorded. Effective diagnosis is extremely 
difficult if this step is neglected. 

If byte one of main storage contains an 
S (X'E2*), the following information can be 
obtained easily: 

Check byte X'73' fora X'OF'. This 
indicates either a channel control check or 
an interface control check. Bytes 
X'3A'-X'3B' contain the device address. If 
byte X'73* does not contain a X'OF', a 
machine check must have occurred. 

Byte one may have a W. If a W (X'E6') 
is found, a hard stop on SYSRES is 
indicated. 

If the CPU detects an error in its own 
circuitry, or (in the System/360, model 50 
or smaller) in the channel or interface 
control circuits, it forces a machine check 
interrupt. The system places an S in byte 
1 and enters a hard wait. The S is a 
request to run the SEREP (System 
Environmental Recording, Editing, and 
Printing) dump to format and display the 
contents of the CPU's hardware registers 
and log-out area for use by the customer 
engineer. (A SEREP dump configured for the 
system should be available to the operator. 
A copy can be obtained from the customer 
engineer responsible for the CPU.) 
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Byte 


Byte 1 


Byte 2 


Byte 3 


Explanation 


SYSTEM/360 SEREP Codes: 


X'OO' 


X'E2' 


Not used 


Not used 


Machine check. Load SEREP. Re - IPL system. 


X'01' 


X'E2' 


Reserved 


Reserved 


Channel failure: interface or channel control check . Load SEREP. Re - IPL system. 


SYSTEM/ 


370 SEREP Codes: 






x'cr 


X'E2' 


A, 1, S* 


Not used 


Unrecoverable machine check . 


X'C2' 


X'E2' 


Not used 


Not used 


Unrecoverable channel failure during RMS fetch. 


X'C3' 


X'E2' 


A, 1, S* 


Not used 


Channel failure on SYSLOG when RMS message scheduled. 


X'C4' 


X'E2' 


A, 1, S* 


Not used 


Reserved (should not occur) 


X'C5' 


X'E2' 


A, 1, S* 


Not used 


Channel failure: ERPIBs exhausted . 


X'C6' 


X'E2' 


A, 1, S* 


Not used 


Channel failure; two channels damaged or a damaged channel situation occurred while 
RMS was executing an I/O operation . 


X'C7' 


X'E2' 


A, 1, S* 


Not used 


Channel failure; system reset was presented by a channel . 


X'C8' 


X'E2' 


A, 1, S* 


Not used 


Channel failure; system codes in ECSW are invalid. 


X'C9' 


X'E2' 


A, 1, S* 


Not used 


Channel failure; channel address invalid. 


SYSTEM/ 


360 and SYS 


TEM/370 W/ 


\\1 Codes: 




X'03' 


X'E6' 


Channel 


Unit 


DOS unrecoverable disk error during program fetch . The first six sense bytes are 
placed in hex bytes 5- A. Re -IPL system. 


X'04' 


X'E6' 


Not used 


Not used 


Cancel condition has occurred while performing a Supervisor fundtion (not a Supervisor 
detected problem -program error). Normally a Program Check while in Supervisor State. 
This condition also occurs if a fetch has been issued for and IBM -supplied transient 
which is not in the system core image library. IBM -supplied $$A, $$B, and $$R 
transients cannot be placed in a private core image library. Take a stand-alone dump; 
the name of the transient involved is in the first 8 bytes of the appropriate transient 
area. Place the transient in the system core image library. Re -IPL system. 


X'05' 


X'E6' 


Channel 


Unit 


I/O Error Queue has overflowed as the result of an I/O error on a program fetch 
channel program. Re -IPL system. 


X'06' 


Not used 


Not used 


Not used 


Reserved (should not occur). 


X'07' 


X'E6' 


Channel 


Unit 


IPL I/O error. Channel can unit indicate whether SYSRES or communication device. 
Re -IPL system. 


X'08' to 
X'60' 




Channel 


Unit 


Error recovery messages. Refer to OP messages in DOS Messages, found in Preface. 



* Note: A (X'Cl ') = SYSREC error recording unsuccessful 
I (X'C9') = SYSREC error recording incomplete. 
S (X'E2') = SYSREC error recording successful . 

Figure H.8. Low Core Error Bytes 
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If a program check interrupt occurs 
while the DOS supervisor is in control of 
the system, the integrity of the control 
program itself is in doubt. System 
response is to put a message of 04W 
(X'OUEe 1 ) in bytes and 1 and enter a hard 
wait. Note that many programs may run in 
the supervisor state and hence cause this 
type of hard wait. These programs include 
BTMOD (in its channel appendage routine) , 
SPOOLing programs such as POWER (which 
alters the address of the SVC new PSW to 
point to the POWER partition) , most $$A and 
some $$B transients. 

After the 04W message has been noted, a 
stand-alone dump should be taken. The 
first diagnostic steps, as with any program 
check, are to locate the failing 
instruction and determine the program in 
error. Use the supervisor assembly listing 
to determine if the program check address 
(location X , 2D , -X , 2F t ) falls within the 
supervisor nucleus (address less than label 
NUCEND) , within the logical transient area 
(label LTA to LTA+X ' 4B0 • ) , the physical 
transient area (label PTA to PTA+X , 228 f ), 
or outside the supervisor (address greater 
than label PPBEG) . 

In the first case, use the supervisor 
listing to find what routine was being 
executed and what function the supervisor 
was attempting to perform. Use the I/O old 
PSW to find the device involved in the last 
I/O interrupt received and the SVC old PSW 
for the last SVC executed. 

In the second and third cases, the name 
of the transient involved appears at the 
beginning of the transient area involved. 
Use the DOS System Generation listed in the 
Preface to find the function of that 
transient. 

When the program check address is 
outside the supervisor, find the partition 
it falls in and use the program 
documentation to locate the failure. 

If W is not present in location 1, 
record the communications region address 
contained in locations X , 16 , -X , 17 t and take 
a stand-alone dump. Check the PIK (located 
at displacement X^E* in the communications 
region) to determine the task in control. 
Then, locate and examine the PIB table 
entry for the task in control. 

The All Bound PIB is usually active, 
indicating an I/O interrupt or event has 
not occurred. The program or task save 
areas indicate the device (s) or resource (s) 
being waited on. The PIB supplies 
information such as the cancel code and the 
address of the partition save area. The 
save area contains the PSW. The 
instruction address portion of the PSW 



should be pointing to the last executed 
instruction. The register values can also 
be helpful at this point. 

Register 14 is used as a standard return 
from an IOCS module. Register 15 contains 
the address of the IOCS module. Register 1 
points to an ECB, RCB, CCB, or last phase 
or transient fetched or loaded. 

Note : Certain unusual hardware and 
software failures can cause the system to 
halt processing with both the system light 
and the wait light on continuously. This 
indicates the current PSW has its wait bit 
set on, but the CPU is operating 
(processing microprogram instructions). If 
possible, the system should be left in this 
state until a customer engineer has 
arrived. A stand-alone dump can show the 
I/O operations in progress. No low-core 
message will be found, and a re-IPL is 
necessary to continue processing. 

By gathering all of the proper 
documentation and using some of the aids 
given in this section, most errors should 
be resolved without too much difficulty. 



Debugging Assembler Programs 



The proper documentation and careful 
interpretation of system messages is needed 
to ensure that the programmer understands 
the diagnostics provided by the system. 
Internal pointers found in the system 
communications region and PIB table allow 
the programmer to analyze main storage 
dumps, to locate programs and save areas, 
and to determine the cause of the error. 

The linkage editor map shows where 
programs should be located in main storage, 
where overlays are loaded, and whether the 
program is relocatable or assembled for 
operation in only one partition. Remember 
that all relocatable programs are assembled 
with a load address of zero in the Disk 
Operating System. 

See Figures 1.7 and 4.4-4.6 for the 
format of the system communications region 
and the PIB table and Figure 1.2 for the 
format of the partition save areas. 



Debugging COBOL Programs 



Debugging information for the COBOL 
programmer includes an example of a program 
named TESTRUN, consisting of a source 
statement listing. Data Division map. 
Procedure Division map, diagnostic 
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messages, linkage editor map, and an 
abnormal termination dump. The IBM Disk 
Operating System Full American National 
Standard COBOL Compiler is used for the 
compilation job step. Figure 4.9 contains 
the program output in its entirety. 

The Data Division map provides the 
internal name generated by the compiler for 
data names and file names defined in the 
program. This internal name is the same as 
that used in the object code listing. An 
address is provided for each name, in the 
form of a base and a displacement. 

The Procedure Division map is a listing 
of the object code. Compiler-generated 
card numbers identify the COBOL statement 
in the source deck containing the verb that 
corresponds to the object code. The object 
code listing also contains the relative 
address of the object code instruction. In 
addition to the object code, a Task Global 
Table (TGT), a Program Global Table (PGT) , 
a literal pool and register assignments are 
provided when a Procedure Division map is 
requested. The TGT is used to record and 
save information needed during the 
execution of the object program. The PGT 
contains literals and the addresses of 
procedure names and generated procedure 
names referenced by Procedure Division 
instructions . 

The linkage editor map contains the load 
address of the program and lists the names 
and locations of COBOL subroutines in main 
storage . 



HOW TO USE A DUMP 



When a job is abnormally terminated due to 
a serious error in the problem program, a 
message is written on SYSLST that indicates 
the: 

1. type of interrupt; for example, a 
program check 

2. hexadecimal address of the instruction 
that caused the interrupt 

3. condition code 

4. reason for the interrupt; for example, 
a data exception. 

The instruction address can be compared 
to the Procedure Division map, where a 
relative address is provided for each 
statement. The load address of the module 
(which can be obtained from the map of main 
storage generated by the Linkage Editor) 
must be subtracted from the instruction 
address to obtain the relative instruction 



address as shown in the Procedure Division 
map. If the interrupt occurred within the 
COBOL program, the programmer can use the 
error address and the Procedure Division 
map to locate the specific statement in the 
program that caused the dump to the taken. 
Examination of the statement and the fields 
associated with it may produce information 
as to the specific nature of the error. 

Figure 4.9 illustrates a dump caused by 
a data exception. Invalid data, that is, 
data that does not correspond to its usage, 
is placed in the numeric field B as a 
result of redefinition. 

• The program interrupt occurred at 
hexadecimal location 0039BC. This is 
indicated in the SYSLST message printed 
just before the dump. 

• The linkage editor map indicates that 
the program was loaded into address 
0032A0. This is determined by 
examining the load point of the control 
section TESTRUN. TESTRUN is the name 
assigned to the program module by the 
source coding: PROGRAM-ID. TESTRUN. 

• The specific instructin which caused 
the dump is located by subtracting the 
load address from the interrupt address 
(that is, subtracting 32A0 from 39BC) . 
The result, 71C, is the relative 
interrupt address and can be found in 
the object code listing. In this case, 
the instruction in question is AP (add 
decimal) . 

• The left-hand column of the object code 
listing gives the compiler-generated 

J * card number associated with the 
instruction. It is card 69. As seen 
in the source listing, card 69 contains 
the COMPUTE statement. 



LOCATING A DTF 



One or more DTF's are generated by the 
compiler for each file opened in the COBOL 
program. All information about that file 
is found within the DTF or in the fields 
preceding the DTF. A particular DTF may be 
located in a system dump as follows: 

1. Determine the order of the DTF address 
cells in the TGT from the DTF numbers 
shown for each file name in the Data 
Division map. 

Note : Since the order is the same as 
the FD's (File Description) in the 
Data Division, the order can be 
determined from the source program if 
the Data Division map is not 
requested. 
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2. Find the relative starting address of 
the block of DTF cells from the TGT. 

3. Calculate the absolute starting 
address of the block by adding the 
hexadecimal relocation factor for the 
beginning of the object module as 
given in the linkage editor map. 

4. Allowing one fullword per DTF cell, 
count off the cells from the starting 
address found in Step 3, using the 
order determined in Step 1 to locate 
the desired DTF cell. 

5. If more than one DTF is generated for 
a file, the above procedure should be 
followed using the PGT and the SUBDTF 
cells rather than the TGT and the 
DTFADDR cells. The order in which 
multiple DTF's appear in main storage 
is dependent on the OPEN option as 
follows : 

(a) INPUT 

(b) OUTPUT 

(c) I-O or INPUT REVERSED 



There can be two or three SUBDTF , s for 
each file with multiple OPEN options. 
The Data Division map sould be used to 
determine the file and the number of 
the SUBDTF CELL assigned to it. 



LOCATING DATA 



The location assigned to a given data name 
may similarly be found by using the BL 
(Base Locator) number and displacement 
given for that entry in the Data Division 
map, and then locating the appropriate 
fullword BL cell in the TGT. The sum of 
the displacement and the contents of the 
cell give the relative address of the 
desired area. This can then be converted 
to an absolute address as described for 
locating a DTF. 



206 DOS System Programmer^ Guide 



o 
ft 
o* 

c 

ua 

> 

Oi 
CO 



to 

O 



01 



■0 





h 





Hi 

ro 



// JOB DTACHK 

// OPTION NODECK, LINK, LIST, LISTX, SYM, ERRS 

// EXEC FCOBOL 



CBL QUOTE, SEQ 


00001 


000010 


00002 


000020 


00003 


000030 


00004 


000040 


00005 


000050 


00006 


000060 


00007 


000070 


00008 


000080 


00009 


000090 


00010 


000100 


00011 


000110 


00012 


000120 


00013 


000130 


00014 


000140 


00015 


000150 


00016 


000160 


00017 


000170 


00018 


000180 


00019 


000190 


00020 


000200 


00021 


000210 


00022 


000220 


00023 


000230 


00024 


000240 


00025 


000250 


00026 


000255 


00027 


000260 


00028 


000270 


00029 


000280 


00030 


000290 


00031 


000300 


00032 


000310 


00033 


000320 


00034 


000330 


00035 


000340 


00036 


000350 


00037 


000360 


00038 


000370 


00039 


000380 


00040 


000390 


00041 


000400 


00042 


000410 


00043 


000420 


00044 


000430 


00045 


000440 


00046 


000450 


00047 


000460 


00048 


000470 


00049 


000480 


00050 


000490 


00051 


000500 


00052 


000510 


00053 


000520 


00054 


000530 


00055 


000534 


00056 


000535 



IBM DOS AMERICAN NATIONAL STANDARD COBOL 



IDENTIFICATION DIVISION. 
PROGRAM- ID. TESTRON. 

AUTHOR. PROGRAMMER NAME. 

INSTALLATION. NEW YORK PROGRAMMING CENTER. 

DATE-WRITTEN. FEBRUARY 4, 1971 
DArE-COMPILED. 07/23/71 

REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 

COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS 

INPUT. 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE- COMPUTER. IBM-360-H50. 
OBJECT-COMPUTER. IBM-360-H50. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO SYS008-UT-2400-S. 

SELECT FILE-2 ASSIGN TO SYS008-UT-2400-S. 

DATA DIVISION. 
FILE SECTION. 
FD FILE-1 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORDING MODE IS F 

RECORD CONTAINS 20 CHARACTERS 

DATA RECORD IS RECORD- 1. 
01 RECORD-1. 

05 FIELD-A PIC X(20). 
FD FILE-2 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MODE IS F 

DATA RECORD IS RECORD- 2. 
01 RECORD- 2. 

05 FIELD-A PIC XC20). 
WORKING-STORAGE SECTION. 
01 FILLER. 

02 COUNT PIC S99 COMP SYNC. 

02 ALPHABET PIC X(26) VALUE IS "ABCDEFGHIJKLMNOPQRSTUVWXYZ". 

02 ALPHA REDEFINES ALPHABET PIC X OCCURS 26 TIMES. 

02 NUMBR PIC S99 COMP SYNC. 

02 DEPENDENTS PIC X(26) VALUE "01234012340123401234012340". 

02 DEPEND REDEFINES DEPENDENTS PIC X OCCURS 26 TIMES. 
01 WORK-RECORD. 

05 NAME- FIELD PIC X. 

05 FILLER PIC X. 

05 RECORD-NO PIC 9999. 

05 FILLER PIC X VALUE IS SPACE. 

05 LOCATION PIC AAA VALUE IS "NYC". 

05 FILLER PIC X VALUE IS SPACE. 

05 NO-OF-DEPENDENTS PIC XX. 

05 FILLER PIC X(7) VALUE IS SPACES. 
01 RECORDA. 

02 A PICTURE S9(4) VALUE 1234. 
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02 B REDEFINES A PICTURE S9(7) COMPUTATIONAL- 3. 

PROCEDURE DIVISION. 
BEGIN. READY TRACE. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

AND INITIALIZES COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO COUNT, NUMBR. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

THEM ON THE CONSOLE. 
STEP-2. ADD 1 TO COUNT, NUMBR. MOVE ALPHA (COUNT) TO 

NAME-FIELD. 

COMPUTE B = B + 1. 

MOVE DEPEND (COUNT) TO NO-OF- DEPENDENTS. 

MOVE NUMBR TO RECORD-NO. 
STEP-3. DISPLAY WORK-RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK-RECORD. 
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL COUNT IS EQUAL TO 26. 

NOTE THAT THE FOLLOWING CLOSES THE OUTPUT FILE AND REOPENS 

IT AS INPUT. 
STEP-5. CLOSE FILE-1. OPEN INPUT FILE-2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES 

OUT EMPLOYEES WITH NO DEPENDENTS. 
STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP-8. 
STEP-7. IF NO- OF- DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO STEP-6. 
STEP-8. CLOSE FILE-2. 

STOP RUN. 
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BALR 


15,0 






000820 


50 00 F 008 




ST 


0,008(0,15) 






000824 


45 00 F 00C 




BAL 


0,OOC(0, 15) 






000828 


00000000 




DC 


X' 00000000' 






00082C 


OA 02 




SVC 


2 






00082E 


41 00 D ICC 




LA 


0,1CC(0,13) 


DTF=2 




000832 


58 FO C 008 




L 


15,008(0,12) 


V(ILBDIMLO) 




000836 


05 EF 




BALR 


14,15 






000838 


58 10 D ICC 




L 


1,1CC(0, 13) 


DTF=2 




00083C 


96 10 1 020 




OI 


020(1), X'10« 




80 


000840 




PN=03 


EQU 


* 






000840 


58 FO C 004 




L 


15,004(0,12) 


V(ILBDDSPO) 




000844 


05 IF 




BALR 


1,15 






000846 


000140 




DC 


X'000140' 






000849 


04F8F0404040 




DC 


X'04F8F0404040' 




80 


000850 


58 10 D ICC 




L 


1,1CC(0,13) 


DTF=2 




000854 


58 FO C 028 




L 


15,028(0,12) 


GN=03 




000858 


91 20 1 010 




TM 


010(1), X' 20' 






00085C 


07 IF 




BCR 


1,15 






00085E 


18 41 




LR 


4,1 






000860 


41 FO C 028 




LA 


15,028(0,12) 


GN=03 




000864 


D2 02 1 025 F 001 




MVC 


025(3,1), 001(15) 






00086A 


58 FO 1 010 




L 


15,010(0,1) 





to 



W 
*< 
W 

ft 
CD 

3 

►a 
n 
o 

iQ 
H 
0> 



(0 



c 

H 

ID 



O 

s 

o 

W 



•d 



o 
h 

3 



o 



to 



8 


00086E 


45 E0 F 008 


BAL 


14,008(0,15) 








000872 


50 20 D ICO 


ST 


2,1C0(0,13) 


BL =2 






000876 


58 80 D 1C0 


L 


8,1C0(0,13) 


BL =2 






00087ft. 


D2 13 6 038 8 000 


MVC 


038(20, 6), 000(8) 


DNM=l-408 


DNM=l-246 




000880 


58 F0 C 018 


L 


15,018(0,12) 


PN=04 






000884 


07 FF 


BCR 


15,15 






80 


000886 


GN= 


03 EQU 


* 








000886 


58 10 C 01C 


L 


1,01C(0,12) 


PN=05 






00088A 


07 Fl 


BCR 


15,1 






81 


00088C 


PN= 


04 EQU 


* 








00088C 


58 F0 C 004 


L 


15,004(0,12) 


V(ILBDDSPO) 






000890 


05 IF 


BALR 


1,15 








000892 


000140 


DC 


X' 000140' 








000895 


04F8F1404040 


DC 


X' 04F8F1404040' 






81 


00089C 


58 20 C 02C 


L 


2,02C(0,12) 


GN=04 






0008A0 


D5 00 C 058 6 043 


CLC 


058(1, 12), 043(6) 


LIT+32 


DNM=2-37 




0008A6 


07 72 


BCR 


7,2 








0008A8 


95 40 6 044 


CLI 


044(6), X'40' 


DNM=2-37+l 






00 08 AC 


07 72 


BCR 


7,2 






81 


0008AE 


D2 00 6 043 C 059 


MVC 


043(1, 6), 059(12) 


DNM=2-37 


LIT+33 




0008B4 


92 40 6 044 


MVI 


044(6), X'40 1 


DNM=2-37+l 




82 


0008B8 


GN= 


04 EQU 


* 








0008B8 


58 10 C 05C 


L 


1,05C(0, 12) 


LIT+36 






0008BC 


50 10 D 1EC 


sr 


1,1EC(0,13) 


PRM=1 






0008C0 


41 20 D 1EC 


LA 


2,1EC(0, 13) 


PRM=1 






0008C4 


58 F0 C 004 


L 


15,004(0,12) 


V(ILBDDSPO) 






0008C8 


05 IF 


BALR 


1,15 








0008CA 


8001 


DC 


X' 8001* 








0008CC 


10 


DC 


X'10' 








0008CD 


00000B 


DC 


X'OOOOOB' 








0008D0 


0C000060 


DC 


X'0C000060' 


LIT+40 






0008D4 


0000 


DC 


X' 0000' 








0008D6 


00 


DC 


X'00' 








0008D7 


000014 


DC 


X' 000014' 








0008DA 


0D0001C4 


DC 


X*0D0001C4' 


BL =3 






0008DE 


0038 


DC 


X'0038' 








0008E0 


FFFF . 


DC 


X'FFFF' 






82 


0008E2 


58 10 C 014 


L 


1,014(0,12) 


PN=03 






0008E6 


07 Fl 


BCR 


15,1 






83 


0008E8 


PN= 


05 EQU 


* 








0008E8 


58 F0 C 004 


L 


15,004(0,12) 


V(ILBDDSPO) 






0008EC 


05 IF 


BALR 


1,15 








0008EE 


000140 


DC 


X'000140' 








0008F1 


04F8F3404040 


DC 


X" 04F8F3404040' 






83 


0008F8 


58 10 D ICC 


L 


1, ICC (0,13) 


DTF=2 






0008FC 


94 EF 1 020 


NI 


020(1), X'EF' 








000900 


18 01 


LR 


0,1 








000902 


18 40 


LR 


4,0 








000904 


41 10 C 048 


LA 


1,048(0,12) 


LIT+16 






000908 


07 00 


BCR 


0,0 








00090A 


05 F0 


BALR 


15,0 








00090C 


50 00 F 008 


ST 


0,008(0,15) 








000910 


45 00 F 00C 


BAL 


0,00C(0,15) 








000914 


00000000 


DC 


X' 00000000' 








000918 


OA 02 


SVC 


2 








00091A 


58 00 D ICC 


L 


0,1CC(0,13) 


DTF=2 






00091E 


41 10 C 050 


LA 


1,050(0,12) 


LIT+24 





o 
fl> 
tr 

c 

ifl 
H» 


O, 
(0 



en 



H 



►0 
H 
<D 

H 
O 

h 

3 



li- 
ve 

O 
hh 

to 



9 


000922 


OA 


02 








SVC 


2 






84 


000924 
000926 


OA 
OA 


OE 
OE 








SVC 
SVC 


14 
14 








000928 


50 


DO 


5 


008 


INIT2 


ST 


13,008(0,5) 








00092C 


50 


50 


D 


004 




ST 


5,004(0,13) 








000930 


58 


20 


C 


000 




L 


2,000(0,12) 


VIR=1 






000934 


95 


00 


2 


000 




CLI 


000(2), X'OO' 








000938 


07 


79 








BCR 


7,9 








00093A 


92 


FF 


2 


000 




MVI 


000(2), X'FF' 








00093E 


96 


10 


D 


048 




01 


048(13), X' 10' 


SWT+0 






000942 


50 


EO 


D 


054 


INIT3 


ST 


14,054(0,13) 








000946 


05 


FO 








BALR 


15,0 








000948 


91 


20 


D 


048 




TM 


048(13), X' 20' 


SWT+0 






00094C 


47 


EO 


F 


016 




BC 


14,016(0,15) 








000950 


58 


00 


B 


048 




L 


0,048(0,11) 








000954 


98 


2D 


B 


050 




LM 


2,13,050(11) 








000958 


58 


EO 


D 


054 




L 


14,054(0,13) 








00095C 


07 


FE 








BCR 


15,14 








00095E 


96 


20 


D 


048 




01 


048(13), X'20* 


SWT+0 






000962 


41 


60 





004 




LA 


6,004(0,0) 








000966 


41 


10 


C 


OOC 




LA 


1, 00C(0,12) 


PN=01 






00096A 


41 


70 


c 


038 




LA 


7,038(0,12) 


LIT+0 






00096E 


06 


70 








BCTR 


7,0 








000970 


05 


50 








BALR 


5,0 








000972 


58 


40 


1 


000 




L 


4,000(0,1) 








000976 


IE 


4B 








ALR 


4,11 








000978 


50 


40 


1 


000 




ST 


4,000(0,1) 








00097C 


87 


16 


5 


000 




BXLE 


1,6, 000(5) 








000980 


41 


80 


D 


1BC 




LA 


8,1BC(0, 13) 


OVF=l 






000984 


41 


70 


D 


1CF 




LA 


7,1CF(0,13) 


TS=01-1 






000988 


05 


10 








BALR 


1,0 








00098A 


58 


00 


8 


000 




L 


0,000(0,8) 








00098E 


IE 


OB 








ALR 


0,11 








000990 


50 


00 


8 


000 




ST 


0,000(0,8) 








000994 


87 


86 


1 


000 




BXLE 


8,6, 000(1) 








000998 


D2 


03 


D 


1E8 C 030 




MVC 


1E8(4, 13), 030(12) 


VN=01 


VNI=1 




00099E 


58 


60 


D 


1C4 




L 


6,1C4(0, 13) 


BL =3 






0009A2 


58 


70 


D 


1BC 




L 


7,1BC(0,13) 


BL =1 






0009A6 


58 


80 


D 


ICO 




L 


8,1C0(0,13) 


BL =2 






0009AA 


58 


EO 


D 


054 




L 


14,054(0,13) 








0009AE 


07 


FE 








BCR 


15,14 








000000 


05 


FO 






INIT1 


BALR 


15,0 








000002 


07 


00 








BCR 


0,0 








000004 


90 


OE 


F 


00A 




STM 


0,14,00A(15) 








000008 


47 


FO 


F 


082 




BC 


15,082(0,15) 








OOOOOC 












DS 


30F 








000084 


58 


CO 


F 


0C6 




L 


12, 0C6(0, 15) 








000088 


58 


EO 


C 


000 




L 


14,000(0,12) 


VIR=1 






00008C 


58 


DO 


F 


OCA 




L 


13, 0CA(0,15) 








000090 


95 


00 


E 


000 




CLI 


000(14), X' 00' 








000094 


47 


70 


F 


0A2 




BC 


7,0A2(0, 15) 








000098 


96 


10 


D 


048 




OI 


048(13), X' 10' 


SWT+0 






00009C 


92 


FF 


E 


000 




MVI 


000(14), X'FF' 








0000A0 


47 


FO 


F 


OAC 




BC 


15,0AC(0,15) 








O0OOA4 


98 


CE 


F 


03A 




LM 


12,14,03A(15) 








0000A8 


90 


EC 


D 


OOC 




STM 


14,12, 00C(13) 








0000AC 


18 


5D 








LR 


5,13 







to 



8 

CO 
CO 
CO 

ft 

3 

h 
o 

uQ 
H 



Q 

C 

Pi 






s 

o 
f 

CO 

ft) 

3 



H3 
H 


H 



ft) 
H 
ft 

H» 
O 


M» 

to 

•J 



0000AE 


98 9F F OBA 


OO0OB2 


91 10 D 048 


0000B6 


07 19 


0000B8 


07 FF 


OOOOBA 


07 00 


0000BC 


00000942 


OOOOCO 


00000000 


OO0OC4 


00000000 


0000C8 


000005EO 


OOOOCC 


000003E8 


OOOODO 


0000064C 


0000D4 


00000928 


0000D8 


C3D6C2C6F0F0F0F1 


OOOOEO 


E3C5E2E3D9E4D540 



LM 9,15, 0BA(15> 

TM 048(13), X'10' 

BCR 1, 9 

BCR 15,15 

BCR 0, 

ADCON L4(INIT3> 

ADCON L4(INIT1) 

ADCON L4UNIT1) 

ADCON L4(PGT) 

ADCON L4(TGT) 

ADCON L4( START) 

ADCON L4(INIT2) 

DC X'C3D6C2C6F0F0F0F1' 

DC X'E3C5E2E3D9E4D540» 



SWT+0 



o 
fl> 

tr 

d 

3 

> 

Oi 
CO 






CROSS-REFERENCE DICTIONARY 



DATA NAMES 



REFERENCE 



o 
o 

w 

& 

CO 

I 



o 
(A 



0) 
n 
ft 

(-» 



Hi 

to 

^1 



FILE-1 

RECORD- 1 

FILE-2 

RECORD- 2 

COUNT 

ALPHA 

NUMBR 

DEPEND 

WORK-RECORD 

NAME- FIELD 

RECORD- NO 

NO-OF-DEPENDENTS 

B 



PROCEDURE NAMES 



00017 


00063 


00063 


00028 


00072 


00072 


00018 


00077 


00077 


00036 


00080 




00040 


00063 


00067 


00042 


00067 


00067 


00043 


00063 


00067 


00045 


00070 


00070 


00046 


00072 


00072 


00047 


00067 




00049 


00071 


00071 


00053 


00070 


00070 


00057 


00069 





STEP-2 
STEP-3 
STEP- 6 
STEP- 8 



00072 00077 



00080 00080 00083 



00067 00067 00070 00074 



00067 00071 



00072 00080 00082 



00081 00081 00081 00081 



REFERENCE 



00067 


00074 


00072 


00074 


00080 


00082 


00083 


00080 



-J 



to 

00 



8 

CO 

CO 

*} 

CO 

ft 

3 

*0 
H 

o 

H 



en 

Oi 



C 
h 
fl> 



o 
o 

CX) 
O 
t" 1 

CO 

3 
•o 

H 

(D 

►t) 
H 
O 

H 
0) 

3 



PJ 
H 
ft 

H 

o 

Hi 
ro 



12 



56 
67 
67 



ERROR MESSAGE 

ILA2190I-W 
ILA5011I-W 
ILA5011I-W 



PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. 
HIGH ORDER TRUNCATION MIGHT OCCUR. 
HIGH ORDER TRUNCATION MIGHT OCCUR. 



ASSUMED POSITIVE. 



o 

c 

US 
vO 
H' 

9 

> 

o> 

CO 






// EXEC LNKEDT 



(0 

H 


H 
0) 

s 





Hi 

to 
-J 



JOB DTACHK 



07/23/71 DISK LINKAGE EDITOR DIAGNOSTIC OF INPUT 



ACTION TAKEN MAP' 

LIST AOTOLINK IJFFBZZN 

LIST AUTOLINK ILBDDSPO 

LIST INCLUDE IJJCPD1 

LIST AOTOLINK ILBDIMLO 

LIST AUTOLINK ILBDMNSO 

LIST AUTOLINK ILBDSAEO 

LIST ENTR¥ 



0001 



to 

V0 



to 
to 
o 



8 

w 

CO 

»< 

(0 

rt 

3 

H 







o 
o 

td 
o 

CO 



T3 



07/23/71 PHASE XFR-AD LOCORE HICORE DSK-AD ESD TYPE LABEL LOADED REL-FR 

PHASE*** 0032A0 0032A0 004ADB 63 07 2 CSECT TESTRUN 0032A0 0032A0 

CSECT IJFFBZZN 003C50 003C50 

* ENTRY IJFFZZZN 003C50 

* ENTRY IJFFBZZZ 003C50 

* ENTRY IJFFZZZZ 003C50 

CSECT ILBDSAEO 0049F0 0049F0 

ENTRY ILBDSAE1 004A06 



CSECT 



ILBDMNSO 0049E8 0049E8 



CSECT ILBDDSPO 0041B8 0041B8 

* ENTRY ILBDDSP1 004708 

* ENTRY ILBDDSP2 0047A0 

* ENTRY ILBDDSP3 004958 



c 

H- 
Qj 
(0 



CSECT 



ILBDIML0 004990 004990 





ua 
n. 



H. 

ft 

H 

o 

Hi 

to 



CSECT IJJCPD1 003FC0 003FC0 

ENTRY IJJCPD1N 003FC0 
* ENTRY IJJCPD3 003FC0 




I Figure 4.9. COBOL Sample Program (Part 15 of 27) 
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o 

? 

H« 

9 

> 
(0 



to 

U) 



H 



O 
O 

a 
o 

W 



K 


H 
(U 

3 



-J 

O 
t-h 

■J 



GR 0-7 
GR 8-F 
FP REG 
COMREG 

000000 
000020 
000040 
000060 
000080 
0000A0 

ooooco 

0000E0 
000100 
000120 
000140 
000160 
000180 
0001A0 
0001C0 
0001E0 
000200 
000220 
000240 
000260 
000280 
0002A0 
0002C0 
0O02E0 
000300 
000320 
000340 
000360 
000380 
0003AO 
0003CO 
0003EO 
000400 
000420 
000440 
000460 
000480 
0004A0 
0004C0 
0004E0 
000500 
000520 
000540 
000560 
000580 
0005A0 
0005C0 
0005E0 
000600 
000620 
000640 
000660 


DTACHK 

00003850 00003960 
000035B8 00003BE2 
00000000 00000000 
BG ADDR IS 000208 

00000000 00000000 
FF050007 40002E06 
00002F28 OCOOOOOO 
00040000 00000336 
00000000 00000000 
0146940F B47B41A0 
06B006BO 06B006B0 
A00C4710 00EA9260 
010E9104 A0004780 
C0440778 94F9703B 
4570B218 07F842B0 
C0441BAA DD06BEEE 
A0009140 A0014710 
4BA00262 41AAC000 
9030989D 01F08200 
41100030 47F0B166 
00003000 80001048 
C4E3C1C3 C8D24040 
A8A07CD0 00C62171 
00002044 OOOOOOOC 
01001F98 20000000 
00001F2C 00000000 
0000289C 00003228 
48A00236 4AA00262 
41DCB000 07F99601 
48E001C8 D207BF50 
02E04190 01B69500 
48667000 07F6181F 
1B234740 03904130 
00CA4230 04D94820 
960C1004 07F91858 
03CC4284 000007F9 
95600237 47800366 
4121000F 4570BCAC 
92FF04D9 D200044D 
20004870 02544338 
B60ED501 0022BB2C 
00234780 04AE9110 
0274D200 04B14000 
4780B62E 47F004EC 
02CC9507 60004770 
02D04144 0000D503 
91406004 47800560 
D2034000 700195FF 
48603000 95003000 
50184780 08409101 
95035018 47D00634 
9C000184 4770Q5F2 
00454770 060C91AF 
58600048 4A60BDDC 
47700654 45700B84 
477005D0 45700B84 


07/23/71 

00000001 
000032A0 
00000000 

00000000 
FFl 50007 
00001D38 
00040000 
00000000 
C0544570 
06B041BB 
A00195E2 
010E9203 
D7017058 
00E748B0 
000C43A1 
BB64D207 
D2010016 
00389284 
96030039 
F0F761F2 
0007AFFF 
21782269 
22E21E4E 
00000000 
00000000 
100020CE 
9180A000 
A00048B0 
E00094FD 
00234780 
1B664121 
00151B23 
02364322 
41430002 
95FF04B1 
D502A005 
D5021009 
A00D4123 
70004930 
4780B8E4 
30064780 
50104000 
5880BF8C 
0566D202 
70014000 
94BF6004 
30024770 
47800592 
100C4710 
9560C09C 
4032C0B4 
00440789 
50600040 
9120800F 
4B800262 


00000001 
000032A0 
00000000 

00000000 
E00039C2 
00000000 
0000147A 
00000003 
0B8418A8 
001741BB 
A0024780 
008F9281 
70589283 
02C847F0 
000742A0 
01F09008 
A0009898 
C0A4D207 
82000038 
F361F7F1 
00004ADB 
226A0000 
1EF41F04 
02080000 
00000000 
00001DC8 
47100306 
02C841CB 
BF51D213 
03F49526 
000F4570 
47B00392 
C0031A23 
43540000 
07891B00 
02814770 
023947B0 
000BD5Q0 
BE3847B0 
D501BE4C 
B2384180 
92FF4000 
44000CB8 
02CD6001 
47800566 
91101002 
03C64280 
9F006000 
05D0940F 
4780067C 
96803006 
D201003A 
4032C0B4 
47100094 
4878C000 


0000338A 
00003880 
00000000 

00000000 
5B5BC2C5 
F75A1C00 
00000000 
00050003 
41900156 
00504570 
0DC695C1 
A0004BA0 
A0009680 
BC704570 
023741AA 
68009058 
90108200 
01F0BF50 
FF050007 
32A03000 
00004ADB 
25102514 
1F140020 
00000294 
00000000 
00002A9C 
58B0A004 
B00041DC 
BF5801F0 
002347B0 
BCAC4860 
1A234220 
950B1007 
41455000 
5000BF74 
04204111 
00C61B33 
1007A00E 
03B88930 
BE5A4720 
00014148 
42205000 
9560C09C 
587002CC 
9120100C 
47800558 
30029198 
07694060 
06FF91F0 
D2020049 
07F94730 
05E29550 
47F0089A 
47F0065C 
91407038 


50003C12 
00003688 
00000000 

00000208 
D6D1F440 
01BB0994 
OOOOOBBC 
06B006BO 
4180B2CE 
01464180 
A0024780 
0262487A 
A0014400 
BC70D205 
C0444400 
68209060 
01F04400 
9890BF58 
40002E06 
00000000 
00000010 
25183CF0 
214C0010 
00000000 
00000000 
923801C9 
9018B030 
B00095FF 
07F9909D 
00BE4860 
BE5C1B22 
04D94320 
47F00454 
1A444A40 
95FF04B1 
00004910 
43301007 
47B000CA 
00034A30 
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003280 
0032A0 
0032C0 
0032E0 
003300 
003320 
003340 
003360 
003380 
0033A0 
0033C0 
0033E0 
003400 
003420 
003440 
003460 
003480 
0034A0 
0034C0 
0034E0 
0036C0 
0036E0 
003700 
003780 
0037A0 
0037C0 
0037E0 
003800 
003820 
003840 
003860 
003880 
0038A0 
0038C0 
0038E0 
003900 
003920 
003940 
003960 
003980 
0039A0 
0039CO 
0039E0 
003A00 
003A20 
003A40 
003A60 
003A80 
003AA0 
00 3AC0 
003AE0 
003B00 
003B20 
003B40 
003B60 
003B80 
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05F00700 
FFFFFFDC 
00005218 
00000000 
00000000 
47F0F0AC 
000032A0 
E3C5E2E3 
E6E7E8E9 
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01010014 
00003430 
00000000 
00000014 
00000000 
10003C50 
41E0E001 
00640063 
00000000 
00000000 
00000000 
00000000 
00000000 
00003550 
000032A0 
00010000 
00000000 
00000000 
00000000 
00000000 
000049E8 
00003A5E 
5B5BC2D6 
E6D6D9D2 
58F0C004 
4500F00C 
5870D1BC 
4830C03A 
C03A4A30 
48206000 
C03C4140 
E0009240 
4004F7F2 
60385810 
C004051F 
60004930 
00014004 
4500F00C 
5000F008 
58F0C004 
41F0C028 
58F0C018 
D500C058 
4120D1EC 
FFFF5810 
18011840 
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00000000 
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000035B3 
00000000 
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00000000 
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00003958 
000032A0 
000032A0 
00003958 
— SAME — 
00000000 
00003550 
0000338A 
000041B8 
00003A72 
D7C5D540 
60D9C5C3 
051F0001 
000033F8 
D2016000 
4A306000 
601C4E30 
4C20C03A 
601E4820 
60444830 
40404000 
D1C81841 
00014004 
C03E58F0 
F7F74040 
00000000 
4500F00C 
051F0001 
D2021025 
07FF5810 
60430772 
58F0C004 
C01407F1 
4110C048 
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00000000 

58EOC000 
90ECD00C 
00003880 
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F2F3F4F0 
E8C34000 
00000000 
10003C50 
41E0E001 
00640063 
00000000 
E2F0F0F8 
020035B8 
00004A06 

00000000 
000033F8 

00003550 
000033F8 
00003880 
00000000 

00000000 
000035B8 
00000000 
00004990 
00003B26 
5B5BC2C3 
D6D9C400 
4004F6F3 
0A024100 
C038D201 
4E30D1D0 
D1D0D705 
1A425B40 
60004C20 
601C4E30 
58F0C004 
58F01010 
F7F44040 
C024078F 
40005810 
0A025800 
00000000 
4004F8F0 
F00158F0 
C01C07F1 
95406044 
051F8001 
58F0C004 
070005FO 
50D05008 


000032A0 
00004DB6 
00000000 

58D0F0CA 
185D989F 
00003688 
C3C4C5C6 
F1F2F3F4 
00404040 
00000000 
1160E2E8 
58201044 
00000000 
04000000 
40400272 
00000064 
000049F0 

00000000 
00003550 

01000000 
50003C12 
00003960 
00000000 

00000000 
00003388 
00000000 
00003950 
00003B58 
D3D6E2C5 
58F0C004 
40404000 
D1C858F0 
601CC038 
D705D1D0 
D1D0D1D0 
C0385040 
C03A1A42 
D1D0F331 
051F0002 
45E0F00C 
40005800 
5810C00C 
D1C894EF 
D1C84110 
0A024100 
40404000 
101045E0 
58F0C004 
0772D200 
1000000B 
051F0001 
5000F008 
5050D004 


000032A0 
0A0407F1 
00000000 

9500E000 
F0BA9110 
000038EC 
C7C8C9D1 
F0F1F2F3 
40404040 
10000000 
E2F0F0F8 
010034E8 
00000000 
00008200 
00000000 
00003620 
00000000 

7000004B 
000032A0 

70003934 
00003388 
000041B8 
00000000 

00000000 
000033F8 
00003A3E 
00003A3E 
00003A3E 
5B5BC2C6 
051F0001 
4110C040 
C00805EF 
58F0C004 
D1D0940F 
940FD1D6 
D1DC58E0 
5B40C038 
603AD1D6 
00000014 
5020D1BC 
D1E85000 
07F15800 
10201801 
C0500A02 
D1CC58F0 
5810D1CC 
F0085020 
051F0001 
6043C059 
0C000060 
4004F8F3 
4500F00C 
5820C000 


0007AFFF 
000032B0 
00000000 

4770F0A2 
D0480719 
00003BC8 
D2D3D4D5 
F4F0F1F2 
00000000 
04000000 
40400162 
20000064 
000049F0 
00000108 
20000000 
00000000 
00000000 

00000000 
000033F8 

000041B8 
00003550 
00003850 
00000000 

00000000 
00003470 
00000000 
00003AE0 
000032A0 
C3D4E4D3 
4004F6F0 
5800D1C8 
5810D1C8 
051F0001 
D1D64F30 
4F30D1D0 
D1DCD200 
5040D1E0 
96F0603D 
0D0001C4 
5870D1BC 
D1E45800 
D1E45000 
18404110 
4110C040 
C00805EF 
58F0C028 
D1C05880 
4004F8F1 
92406044 
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40404000 
00000000 
95002000 
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000032B0 
00000000 

9610D048 
07FF0700 
C3D6C2C6 
D6D7D8D9 
F3F4F0F1 
F1F2F3C4 
00009200 
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00003550 
01010014 
000034A8 
00000000 
00000014 
00000000 
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00003850 
000035B8 
00004708 
00000000 

000032A0 
00000000 
00000000 
00003B2C 
00000001 
F0E90000 
40404000 
184005F0 
96101020 
4004F6F7 
D1D04030 
4030601C 
6038E000 
58E0D1E0 
58FCC004 
0038FFFF 
5810D1E8 
C0205000 
D1E858F0 
C04805F0 
5800D1CC 
5810D1CC 
91201010 
D1C0D213 
40404000 
5810C05C 
00140D00 
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0A025800 
077992FF 
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00003BE2 
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E2E3E4E5 
F2F3F4F0 
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00003550 
00000000 
00000000 
86BCF018 
00000000 
00000000 

000038EC 
00000000 

00003960 
00003BE2 
00003550 
00000000 
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0000001C 
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00003B88 
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9640D048 
5000F008 
5020D1BC 
40404000 
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41406002 
FA.306050 
D2006043 
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D2137000 
07F158F0 
D1E84830 
C004051F 
5000F008 
184005F0 
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071F1841 
60388000 
5820C02C 
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01C40038 
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D1CC4110 
20009610 
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003BE0 
003C00 
003C20 
003C40 
003C60 
003C80 
003CA0 
003CC0 
003CE0 
003D00 
003D20 
003D40 
003D60 
003D80 
003DA0 
003DC0 
003DE0 
003E00 
003E20 
003EaO 
003E60 
003E80 
003EA0 
003EC0 
003EE0 
003F00 
003F20 
003F40 
003F60 
003F80 
003FC0 
003FE0 
004000 
004020 
004040 
004060 
004080 
0040A0 
0040C0 
0040E0 
004100 
004120 
004140 
004160 
004180 
0041A0 
0041C0 
0041E0 
004200 
004220 
004240 
004260 
004280 
0042A0 
0042C0 
0042E0 
004300 
004320 
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D04850E0 
D0484160 
4180D1BC 
D1C45870 
47F0F27A 
103C4570 
F0369071 
4570F260 
0A074200 
07FE9104 
101547E0 
0A.009180 
58B01038 
48B01000 
4770F140 
96801015 
OA0007F7 
F1B89108 
5810104C 
F1F694DF 
0A320000 
0A3298F1 
F35805EE 
47E0F0E8 
41E0F296 
F2609120 
104C58E0 
4780F2FA 
10284400 
00000000 
5B5BC2C5 
F1CC9104 
102B4710 
4780F068 
94BF102C 
91801002 
07F31831 
1030D24F 
4710F11E 
102C4710 
1050D500 
19434770 
10364720 
1052F1C8 
0A021812 
F9C3F14E 
C4E2D7F0 
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4770F08A 
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F126D200 
58440000 
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4A510002 
4710F116 
D0FC4580 
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D05405F0 
00044110 
4170D1CF 
D1BC5880 
47F0F052 
F0CA9871 
F32C58C0 
91801002 
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D0601004 
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9120D048 
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05105800 
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F32C4400 
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4710F07E 
10000AOO 
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91201002 
58B01038 
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E03098F1 
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47F0F02A 
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F0E85846 
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910F1000 
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41BB0000 
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5810F354 
F21A9512 
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00000640 
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18534800 
00084620 
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91201000 
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4770F162 
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12BB4740 
947F1015 
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100047F0 
987DF32C 
D203F358 
F20A58E0 
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F3289680 
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F35C94F7 
F32C5870 
F2D2D703 
5070F328 
F28A9120 
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F1CC9620 
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4110F31E 
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D703104C 
91401002 
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00000000 
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104A9103 
F1DF1930 
4780F088 
4780F0E8 
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10485830 
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D2001040 
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D503103C 
1050D501 
41101016 
000048E0 
C9D3C2C4 
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95401000 
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010C416D 
18851288 
F126D200 
18E141EE 
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80034770 
9101F7A0 
D14447F0 
4870F6D0 
F2B258F1 
D1594710 
D201F6D0 
4110F7D0 
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F5389209 
4770F37C 
4000580D 
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12774780 
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D0605810 
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9815D060 
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F6D4D203 
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002C4166 
F538581D 
1B00D201 
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F7C04E1D 
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000147F0 
00000000 
0C000003 
00000800 
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20000001 
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D060415D 
96F0D068 
9601D15A 
47F0F440 
91101000 
F49047F0 
41500003 
47F0F51A 
4770F4E4 
F1B61255 
F4A44111 
090046F0 
00004778 
002010F1 
13000000 
08004768 
08004788 
00003FC0 
80000000 
00000051 
1D0047EC 
1E004830 
00000000 



D0FC47F0 
1B781B58 
000AD501 
D10807F1 
F6D0F6D2 
9104D105 
4500F264 
4160F728 
D2076048 
06709240 
004847F0 
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58A20000 
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47F0F4D0 
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47F0F4A4 
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00000000 
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30000081 
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Debugging FORTRAN Programs 



When debugging FORTRAN programs, gather the 
program listing, linkage editor map, main 
storage dump, and any system messages. The 
linkage editor map is the most useful 
documentation. Using this map together 
with the main storage dump, the programmer 
can locate such information as DTF tables, 
I/O areas, logic modules and FORTRAN 
subroutines used at object time. 

A sample FORTRAN program, linkage editor 
map, and storage map are included to show 
the relationship between the linkage editor 
map and the contents of main storage, and 
to indicate where the DTF tables and I/O 
areas are located (see Figure 4.10). The 
DTF tables are built as they are opened, 
starting from the end of main storage or 
the end of the partition in which the 
program is loaded. The I/O areas directly 
follow the end of the problem program. The 
FORTRAN program itself builds only one I/O 
area. 



User-written code is always the first 
item in main storage followed by the object 
time FORTRAN subroutines to perform the 
functions required by the problem program. 
Only one logic module is accessed by all 
FORTRAN I/O units (except console 
typewriter) for each FORTRAN program. The 
console typewriter uses its own DTFCN that 
includes a logic module to handle all 
console typewriter functions. Each FORTRAN 
program includes an I/O unit table to 
convert a FORTRAN unit to a DOS symbolic 
unit. 



FORTRAN uses the STXIT macro to handle 
its own program checks. It also uses the 
normal DOS register conventions. In 
addition, register 13 is the base register 
for the FORTRAN in-line code and points to 
the register save area. Register 15 is the 
base register for FORTRAN object time 
subprograms . 
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// OPTION OUMP.LINK 

// EXEC FFORTRAN 



// FTC LISTX,NAME-SAMP2- Refer to hex '18' in LISTX Map. 

MAP YES 

LOAD =4 

DECK NO 

LIST YES Output A Listing 

LISTX YES - Output Object Module Listing 
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00S FORTRAN IV 360N-F0-479 3-0 



SAMP2 



DATE 



11/11/68 



TIME 



00.00.06 



PAGE 0001 



0001 
0002 

0003 
0004 
0005 
0006 
0007 
COOS 
0009 
0010 
0011 
0012 
0013 
0014 



Internal 

Statement 

Number 

assigned by 

FORTRAN 

Compiler. 



PRIME NUMBER GENERATOR 
WRITE (3.1) 

1 FORMAT IMF0LL0WING IS A LIST OF PRIME NUMBERS FROM 2 TO 1000'/ 
119X,1H2/19X,1H3) 

00 4 I»5,1000,2 

K*SQRT(FL0AT(I)) 

00 2 J=3,K,2 

IF (MOOdtJI .EQ. 0) GO TO 4 

2 CONTINUE 
WRITE (3.31 I 

3 FORMAT (120) 

4 CONTINUE 
WRITE (3,5) 

5 FORMAT (• THIS IS THE END OF THE PROGRAM') 
STOP 

END 
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SYMBOL LOCATION 
I AO 



SYMBOL 
IBCOH= 
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SCALAR MAP 
SYMBOL LOCATION SYMBOL LOCATION 
K A4 J A8 



SUBPROGRAMS CALLEO 
SYMBOL LOCATION SYMBOL LOCATION 
SORT 
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LOCATION 



SYMBOL 



Locate these values in storage print. 

P. P. begin = 2800 Variable = 2800 + DSP. 
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Displacement to an adcon containing the address of subprograms. Check in 
storage' print and use Linkage Editor Map. 
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FORMAT STATEMENT MAP 
SYMBOL LOCATION SYMBOL LOCATION 
3 108 5 IOC 
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SYMBOL 



LOCATION 




Displacement to symbols used on FORMAT STATEMENTS. Locate the beginning of 
Symbol 1 in dump and cross-reference to LISTX Map. Check the LISTX Map for the 
internal statement numbers 2, 9, and 12. They are not there because a Format Source 
Statement causes a constant to be assembled rather than machine instructions. 
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TIME 
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LOCATION 
000000 
Hex 000002 
000006 
^00000A 
00000E 
000012 
000014 
000018 
00001C 
000020 
000024 
000028 
000174 
000178 
0001 7C 
000180 
000184 
000186 
00O18A 
00018C 
00018E 
000192 
000194 
000198 
00019C 
0001AO 
0001A4 
0001A8 
0001AC 
OOOIBO 
0001B4 
0001B8 
0001BA 
0001RE 
0001C2 
0001C6 
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0001CA 
0001CE 
0001O0 
000104 
0001D8 
00010C 
00010E 
0001E2 
0001E4 
0001E6 
0001EA 
0001EE 
0001F2 
0001F4 
0001F6 
0001FA 
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Number 



X Instruction 
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OPERAND 



BCD OPERAND 



15,0 

2,3,341151 

13,30(0,15) 

15,2(0.15) 

15,4(0,13) 

15,2 



Establish Addressability 
for Program 



OOCOOOOO 
E2C104 






P24040 \ 



00000000 'No. of chars. 
00000000 th at can be used 
OOOOOOOn in a CALL Stmt. 



_A4_ 

Program Name 

~~ A20 
A36 
A52 



13,4(0,13) 
14,12(U.li) 
2,12,28(13) 
12(13), 255 
15,14 



15,128(0,13) 



12,13 
13,4 

14,64(0,15) 
13.12 



Address constant labels are prefixed with an 'A' 



IBCOM= 



Program Initialization 

Example: IBCOM will issue STXIT macro so FORTRAN 
can handle its own program checks. 



15,128(0,13) 

14,4(0,15) 

00000003 

000000C4 

15,128(0,13) 

14,16(0,15) 



IBCOM= H 



• Subprogram address being loaded. 
■Name of a subprogram (I/O) 
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0. 31 , 6(0.13) 
0,116(0.13) 
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1,280( 

0,276( 

0,260( 

0,0 

14,0 

11,6(0 

0,0 

0,320( 

l,136( 

15,132 

14,15 

0,4(0, 

2,2 

2.0 

2,292( 

2,284( 

0,2881 

2,2 

14,0 

11,6(0 

0,0 



1S7TTT 

0.13) 
0,13) 
0,13) 



14) 

0,13) 
0.13) 
10,13) 

0) 



0,13) 
0,13) 
0,13) 



Refer to internal statement 3. 

Variable I is initialized to 5. 

Look at storage print. Problem program 

area begins at 2800. R13 = 282C 

316 = 13C in hex and 116 = 74 in hex. 



282C 
+ 13C 

2968 — Initialization 
Value 



282C 
74 
28A0 — Location 
of I 



SORT 



The easy way to locate variables is to use the Storage Map. 
-Subprogram address being loaded. 



-Name of a subprogram (square root). 
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000200 

000204 

000208 

00020C 

000210 

000214 

000218- 

00021C 

00021E 

000222 

000226 

000228 

00022C 

000230 

000234 

000238 

00023C 

000240 

000244 

000248 

00024C 

000250 

000254 

000258 

00025C 

000260 

000264 

000268 

00026C 

000270 

000274 

000278 

00027C 

000280 

0C0284 

000288 

00028C 

000290 
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DATE U/lt/68 



TIME 
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L 

BAL 
DC 
DC 
L 

BAL 

DC 

_BAL_ 



L 

L 

LA 

LA 

BXLE 



L 

BAL 

OC 

DC 

BAL 



L 

BAL 
OC 
DC 



END 
000292 

T 



0.120(0.13) 



0,32410,131 
0,12410.131 



U.llfclO.UJ 

0,32(0) 

0,12410,13) 

0,124(6,13) 

1,116(0,13) 

1,1 

1,260(0,13) 

14,96(0,13) 

8.14 



0,124(0,13) 



2,2(0,0) 

3,120(0,13) 

0.2.0(1) 



15,128(0,13) 

14,4(0,15) 

OOC00003 

00000108 

15,128(0,13) 

14,8(0,15) 

0450D074 

14.16(0.15) 



0,116(0,13) 

1,100(0,13) 

2,2(0,0) 

3,1000(0,0) 

0.2.0(1) 



15,128(0,13) 
14,4(0,15) 

00000003 
00000 IOC 
14,16(0,15) 



15,128(0,13) 
14,52(0,15) 

05404040 
40F0 



BYTES 



TOTAL MEMORY REQUIREMENTS 

HIGHEST SEVERITY LEVEL OF ERRORS FOR THIS MOOULE MAS 



J 

±21 



IBCOM= 



IBCOM= 



^t 



00.00.06 



PAGE 0004 



Internal Adcon used in this case for 
the limits of a DO LOOP. 



IBCOM* 



tBCOM= 



Hex number of bytes. 
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11/11/68 PHASE XFR-AD LOCORE HICORE DSK-AO ESD TYPE LABEL 



LOADED REL-FR 



PHASE*** 002800 002800 005FF7 IA 06 1 CSECT 



The program name is contained at dis- 
placement of X'18' in USTX Map. 



SAHP2 
Z3 



002800 002800 



Problem Program begin. 



A member of the FORTRAN System 
Library that performs object time 
implementation of I/O source state- 
ments and handles all abnormal or 
normal termination of FORTRAN 
object time programs. 



A member of the FORTRAN System 
Library used to calculate square roots. 



A member of the FORTRAN System Library processes 
arithmetic-type and specification program interrupts 
and continues EXECUTION. It also fixes any boundary 
alignment error that occurs. 



A member of the FORTRAN System library 
that performs INPUT and OUTPUT data 
conversion. 



A member of the FORTRAN System Library that 
performs object time I/O data management. 



CSECT 
ENTRY 

• ENTRY 
ENTRY 
ENTRY 
ENTRY 

• ENTRY 

[CSECT 
ENTRY 

TCSECT 

L ENTRY 

CSECT 

ENTRY 
ENTRY 
ENTRY 
ENTRY 
ENTRY 
ENTRY 
ENTRY 

CSECT 

ENTRY 
ENTRY 
ENTRY 

• ENTRY 



ILFIBC0M 

IBCOM* 

0PSYS 

INTSW 

PDPAR 

DUMPSW= 

IJTINTSW 

ILFSS0RT 
SORT 

ILFFINT 
SAVERR 

ILFAOCON 
ILFFCVEO 
ILFFCVL0 
ILFFCVIO 
ILFFCVC0 
ILFFCVA0 
ILFFCVZO 
INT6SW 

ILFFI0CS 

ILFFB0RG 

ILFBFORG 

IJSYSL0 

A0I0CR= 



002A98 
002A98 
003750 
0038A1 
0036C4 
00365A 
0038AI 

005E48 
005E48 

004AC8 
00AFA8 

0039F0 
0044D6 
003C82 
003FD4 
0046F0 
003BF2 
003B4C 
004AB0 

005098 
005AFC 
005AF8 
005B08 
005A54 



A member of the FORTRAN System Library that 
contains a Unit Table that is used to convert from 
a FORTRAN unit to a DOS symbolic unit. 



t 



CSECT 



1LFUNTAB 005EF8 



I/O LOGIC MODULE used by all I/O units except 
console. 



CSECT IJJCPDIN 

ENTRY IJJCPD3 



jtCSECT 



005CB8 
005CB8 



A control section in ILFFIOCS that is the logic 
module for the console. 



002A98 



005E48 
004AC8 



'}- 



Refer to FORTRAN storage map for address 
of subprogram. 



Refer to FORTRAN storage map for address 
of subprogram. 



0039F0 



005098 



005EF8 
005C88 



IJ2L0005 005CA8 005098 
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OK 0-7 


0000 )6C 4 


00004FA0 


00002986 


00002974 


O00OFF74 


FFFFFF8C 


00002800 


00002798 










GR 8-F 


000040E8 


0A040 7F1 


00002810 


00002810 


0000282C 


0000282C 


6200290E 


00000000 










FP RcG 

000000 
0000)0 
000060 
000090 

ooooco 

OOOOFO 
000120 


41500000 
00000000 
5B5BC2C5 
00040000 
00000000 
06B006B0 
95E2A002 


00000000 
00000000 
D601F340 
0000020E 
00030005 
06B006B0 
4780090C 


00000000 
00000000 
FF05000E 
00040000 
00030680 
41BR0017 
4BA0023A 


00000000 
00000000 
80000000 
00000F12 
41BB0071 
41880050 
49A0024E 


BE1A2000 
00000000 
00002120 
00000000 
45700128 
45700128 
41AAB8AC 


00000000 
OOOOOIEO 
08400000 
000009F8 
41A0B8BC 
41800138 
077894F9 


4817DF25 

FF070000 
00002118 
00040000 
45700780 
9640A001 
021BD701 


20000000 
00000000 
00000000 
000002 78 
18A84190 
9120A00C 
02380238 


FF050P07 
749077FF 
00000000 
01384180 
4 71000E8 
9680A001 


400070A8 
007FE8B7 
00000000 
0DBC47F0 
9250A001 
9283A000 


FF150001 
00040000 
00000000 
00D806B0 
9281A000 
440003C8 


6200000? 
0F0O0F54 
00002508 
060006BO 
92030005 
0788947F 


A0014570 


001A07F8 


42B000E5 


48B00270 


47F0831A 


4570B31A 


D205B56E 


B5750C05 


B56EB3AC 


1BAADD06 


B56E0012 


43A10007 


000150 


42A0020F 


41AAB8AC 


4400A004 


5890A004 


4220A000 


9140A001 


471001BO 


D20701C8 


90086800 


90586820 


90606840 


90686860 


000180 


90709898 


90108200 


01C84400 


A0045890 


A0049818 


9030989C 


01C88200 


003892R4 


B90CD207 


01C8B5B8 


9890B5C0 


820001Cfi 


000180 


9680AOOO 


41100030 


47F00CA2 


96020019 


82000018 


00000000 


FF050007 


400020A8 


00001000 


00002000 


80000BBC 


00000000 


0001EO 


F1F161F1 


F161F6F8 


28002800 


00000000 


00000000 


00000000 


D8E6C5D9 


E3404C40 


OOOOFFFF 


00005F47 


00005F47 


00000010 


000210 


OOOOFFFF 


E8407E90 


A0A07E00 


00871987 


198E19EF 


19F01A04 


1A221A26 


1A2A38F1 


FIF1F1F6 


F8F3F1F6 


000018AC 


OOOOOOOH 


000240 


1448148E 


1574158C 


15940010 


19640010 


5B5BC2D6 


00020000 


01001800 


1P680000 


OCOOOOOO 


01E00000 


00001AC8 


00002788 


0002 70 


10000000 


00000000 


92380190 


909C01C8 


47F0028C 


5890008C 


45A90060 


4190054C 


48A0020E 


4AA0023A 


9180A000 


471002B2 


0002A0 


58B0A004 


9018B030 


48B002 70 


41CBB000 


07F 99601 


A00048BO 


027041CR 


B00095FF 


A00F0789 


901)0 3500 


48IJ0019C 


0207B5R8 


000200 


000094FO 


B5B9D20F 


85C001C8 


07F9909C 


01C847F0 


03089107 


002347B0 


03089500 


00994780 


03085890 


008CD201 


0090020E 


000300 


41B001C8 


45A90064 


92200190 


45900290 


4190018A 


95000023 


478003B4 


95230023 


47B000BC 


48600022 


1A664866 


B51807F6 


000330 


181F4860 


B49C1B22 


43201007 


4130001A 


1B234740 


03504130 


00101B23 


47B00352 


1A234220 


04634320 


100747F0 


040E4720 


000360 


00C84230 


04634820 


020E4322 


B86B1A23 


950B1007 


47F0040A 


472000C6 


96801002 


960C1004 


07F91858 


41430002 


43540000 


000390 


41455000 


1A444144 


B93895FF 


40004770 


038C4284 


000007F9 


95FF043B 


07891000 


5000B5DC 


95FF043B 


47800D3A 


486002CE 


0003CO 


9560020F 


47800330 


0502A005 


02594770 


03E04UI 


00004910 


B48A47B0 


03E01H66 


4121000F 


4570B356 


1B334330 


10079501 


000 3F0 


10064770 


035E92FF 


04630200 


0403A000 


4123000B 


05001007 


A00E47BO 


00C80403 


1002B918 


41822000 


4870022C 


43387000 


000420 


49308488 


47B00378 


89300003 


4A300220 


91F03004 


4780B076 


41800001 


41488000 


1A444144 


B9381858 


4A50024C 


D200043B 


000450 


40005010 


400092FF 


40004220 


50004260 


500B9203 


501691F0 


30044780 


B09647F0 


04765880 


B7F895FF 


30024770 


03864280 


000480 


30029198 


30060779 


43203000 


4322B905 


48603000 


95003000 


478004A? 


9F006000 


07694060 


04C49120 


30064710 


009A9504 


0OO4B0 


50164780 


0520D202 


00491009 


03000048 


500B9COO 


000E4770 


0404403? 


B91C9680 


30060 7F9 


473007AE 


47F004F2 


5880008C 


0004E0 


909B8050 


18984860 


300045A9 


005C989B 


90509106 


00454770 


09E4913F 


00454 770 


050891AF 


00440789 


4060003A 


58600048 


000510 


4A60B424 


50600040 


4032B91C 


47F00574 


9501500B 


478004B6 


9101100C 


471004B6 


45700780 


0201B3D5 


80024170 


B3C85070 


000540 


00480202 


70091009 


47F004BC 


4190018A 


91060045 


477009EA 


94F00039 


1B224320 


003A4 322 


B9054832 


B91CD500 


30010036 


000570 


47700722 


457006A0 


91020044 


471007C8 


91390045 


477007BC 


91800044 


478005B0 


96040044 


910A0219 


477005B0 


95003004 


0005AO 


477005B0 


9610B8F4 


9603B8EC 


41900134 


91100044 


471005CC 


95000044 


477005C2 


7F90602 


00410041 


477006BA 


91040044 


000500 


477005E2 


95500044 


47700678 


94773006 


07F99477 


30069104 


30064780 


0660D601 


10040044 


94733006 


9180100C 


4710060C 


000600 


95503004 


4780076A 


92003003 


96801002 


9101100C 


4710062E 


45700780 


198A47D0 


06264190 


01349601 


800047F0 


064894FH 


000630 


100C91F0 


30044770 


06484370 


B7FC0670 


4270B7FC 


47F00648 


92FF500B 


43703002 


02003002 


40000200 


4000043B 


4270043B 


000660 


95003000 


47700678 


95FF3002 


07899198 


30064780 


069C07F9 


4832B91C 


D2000689 


003A0570 


41330008 


95013000 


4720074C 


000690 


95FF3002 


07879198 


30060777 


41700490 


1B554350 


30024145 


50001A44 


4144B938 


4A50024C 


58104000 


07F7D201 


10000046 


0006CO 


D202100D 


0041D601 


10040044 


95015016 


47200700 


58700040 


4B70B424 


58770000 


05017000 


B55E4780 


06F8D501 


700088FE 


0006FO 


47700700 


96203006 


96401002 


96011004 


91270044 


477005F4 


96803006 


91041002 


478005F8 


96043006 


95003000 


47700678 


000720 


07F9D200 


0739003B 


D200073F 


003A4832 


B91E4170 


05740560 


950C3001 


07879500 


30004133 


00080706 


47F00678 


4842B91C 


000750 


4832B91E 


45700760 


41330008 


19340729 


95FF3002 


078747F0 


06961B77 


4370)003 


4C70B3DE 


4A700226 


92007000 


47F0060C 


000780 


4880024E 


91F0500B 


47800796 


4380500B 


4183B8AC 


07F79180 


100C4710 


07A6910F 


500B4 780 


07904180 


006047F0 


07900729 


0007B0 


02010044 


B560D202 


0041B421 


92040837 


91090045 


478007F6 


92040837 


58800040 


12884770 


07E69212 


083 79104 


30064780 


0007E0 


080694FD 


08379120 


100C4710 


07F69101 


10024710 


08A095FF 


3002478P 


08069110 


100C4 710 


08A04860 


B49A4960 


B49847B0 


000810 


088C4A60 


B9164060 


B49AD715 


60006000 


02076000 


00404030 


600895FF 


30024770 


08369602 


08379204 


600A9690 


30069102 


000840 


00444710 


084E9130 


00454770 


08009102 


08374780 


08A84186 


OOOC4080 


B3DA4180 


B3D84570 


099447F0 


08C0D300 


B9043004 


000870 


9540B904 


47800918 


95603004 


4780B19A 


95623004 


4780B19A 


47F008D0 


91020837 


47100588 


91010039 


47800902 


47F0009C 


0008A0 


96201002 


47F00588 


9120100C 


47800856 


41810010 


45700994 


47F008C0 


47F00930 


940E0044 


95060044 


47800994 


9220600B 


000800 


45800984 


9102600A 


471008EC 


9502500B 


478008F8 


95FF0219 


478008F8 


41900134 


9287B8FC 


47F00660 


02050005 


600C9706 


000900 


09009701 


09000201 


00023000 


92040000 


92E60001 


820009EO 


94F3600C 


9501600C 


47700800 


91020837 


47100930 


96021003 


000930 


02070040 


60004580 


095E47F0 


05884400 


09304570 


099C47F0 


094A4580 


095F47F0 


05789104 


600A4780 


09304180 


066047F0 


000960 


097496F0 


095F4830 


B4B40257 


B4ACB4C2 


44000DB6 


4870B49A 


4B70B916 


4070B49A 


946F3006 


1B224320 


003A4 322 


B9054570 
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00 
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Hi 



002360 


5BSBC206 


C4E207E5 


00000001 


00000002 


080101B2 


5B5BC206 


C60307E3 


00000001 


002380 


00000002 


08020350 


5B5BC2D6 


C9E2F0F5 


00000001 


00000002 


0901 0300 


5B5BC2D6 


0023A0 


04E3FOF2 


00000001 


00000002 


09020451 


5B58C2D6 


04E3F0F5 


00000001 


00000003 


0023C0 


00010451 


5B5BC206 


04E3F0F6 


00000001 


00000003 


00020451 


5B5BC2D6 


0609FOF1 


0023E0 


00000001 


00000003 


010100F0 


5B5BC2D6 


D7C5D5C3 


ooooooot 


00000003 


010201E3 


002400 


5B5BC206 


07C5D5F2 


00000001 


00000003 


020101EC 


5B5BC2D6 


E2C4C9F3 


OOCOOOOl 


002420 


00000003 


02020190 


5B5BC206 


E2C406F1 


00000001 


00000003 


03010308 


5B5BC2D6 


002440 


E2C4D6F2 


00000001 


00000003 


03020268 


00000000 


00000000 


00000000 


00000000 


002460 


TO THE NEXT 


LINE ADDRESS CONTAINS 


00000000 










002500 


00000000 


00000000 


00002787 


00001E30 


00000280 


00000408 


0000008C 


00000F18 


002520 


000002E2 


00000B56 


OOOOOBCE 


00000000 


00000000 


00000000 


00000000 


00000000 


002540 


TO THE NEXT 


LINE AODRESS CONTAINS 


00000000 










002780 


00000000 


00000000 


00000000 


oooocooo 


FF15C007 


42005DF2 


620050A2 


00005F28 


0027A0 


00005EF8 


0000FF08 


00005A68 


92005302 


00005CB8 


62002040 


0000FF08 


0000001F 


0027C0 


B200505E 


00005E42 


00000008 


0000FF78 


OOOOOOIE 


00006089 


00005870 


00C0032A 


0027E0 


421F9B61 


00000000 


4E000000 


0000001F 


BE158000 


00000000 


92FB4264 


45504206 


002800 


05F09823 


F0225800 


F01E41F0 


F00250F0 


000407F2 


00002814 


06E2C104 


07F24040 


002820 


0000282C 


00002986 


00002974 


C9C7D5D6 


00002804 


E34003C1 


FF0029DE 


00005E48 


002840 


D9C540C5 


05E3D9E8 


40E2E3C1 


E3C504C5 


D5E340D4 


C9E2E2C9 


D5C74B40 


D3CIC2C5 


002860 


0340C240 


C905E2C5 


09E3C5C4 


4B404040 


E340C6C9 


0000282C 


00003824 


0000481C 


002880 


00005814 


D6C3C5C4 


E409C540 


00002A5C 


00002980 


00002A04 


E6C9D5C7 


00002A28 


0028A0 


OOOOOSET^" 


I = 999 *> 
0000001F 


K y 
00000003 


0000TA98 


C0005E48 


^SQRT 

8000296C 


80002974 


800028E0 


0028C0 


80002898 


021A3^fl 


C6D60303 


D6E6C905 


C740C9E2 


40C140D3 


C9E2E340 


06C64007 


0028E0 


09C904C5 


4005E4D4 


C2C5D9E2 


40C60906 


0440F240 


E3D640F1 


FOFOFOIE 


18131A01 


002900 


F21E1813 


1A01F322 


02101422 


021A1F40 


E3C8C9E2 


40C9E240 


E3C8C540 


C505C440 


002920 


06C640E3 


C8C54007 


D906C709 


C1D42209 


00000000 


00000000 


00000000 


00000000 


002940 


4EOO0OOO 


000003E7 


4E000000 0000001F 
/Initial Value I 


4E000000 


00000000 


00000000 


00000000 


002960 


00000C00 


00000000 


00000005 


433E7000 


00000003 


58DOD004 


58EOD0OC 


982C001C 


002980 


92FF0C0C 


07FE58F0 


008018CD 


180445E0 


F04018DC 


58F0D080 


45E0F004 


00000003 


0029A0 


000028C4 


58F00080 


45E0F010 


5800D13C 


5000D074 


58000074 


10105010 


01186800 


0029C0 


O1146A00 


01041200 


05E047B0 


E0062300 


70000140 


41100088 


58F0D084 


05EF4700 


0029E0 


00042B22 


38206E20 


01246020 


D11C5800 


01202222 


05E047B0 


E0061300 


5000D078 


002AOO 


58000144 


5000007C 


5800D074 


8E000020 


5D00007C 


5C00D07C 


5BIOD07A 


13115910 



Debugging RPG Programs 



The documentation for debugging RPG problem 
programs is the source statement listing, 
the linkage editor map and a core dump. 
The memory map of the source statement 
listing gives the displacement of a given 
routine or pointer from the beginning of 
the RPG program and can be used with the 
linkage editor map to locate the DTF 
tables, I/O areas, etc., in main storage. 

A discussion of Halt Analysis is 
included to help determine the cause of an 
HO (internal halt) condition. In addition. 
Figure 4.11 shows how to find the DTF 
pointer containing the address of the DTF 
table of address pointers. Each address 
pointer is four bytes and points to a DTF 
table. Within the DTF table, the 
programmer can locate the CCB that points 
to the CCW chain, that in turn, points to 
the I/O areas. 

A sample source listing, linkage editor 
map and a dump of main storage that 
identifies all program areas can be found 
in Figure 4.13. 



HALT ANALYSIS 



During the execution of an RPG object 
program, the job is canceled if a halt 
indicator is turned on and it is not turned 
off before reading the next input record. 
Before the job is canceled, RPG checks the 
dump option switch in the communications 
region. If the switch is on, a PDUMP of 
the problem program area is given before 
job cancelation. The message "JOB CANCELED 
DOE TO PROGRAM REQUEST" is written on 
SYSLOG whenever a halt indicator (H0-H9) is 
left on. 

When a RPG object program is canceled 
with the preceding message, it must be 
determined which of the halt indicators is 
on. If one or more of the indicators H1-H9 
are on, the programmer must determine the 
reason. For further information on the 
halt indicators H1-H9, refer to RPG 
Specifications listed in the Preface . 

If HO (RPG's internal halt indicator) is 
on, RPG determines the reason. When HO is 
on, a 7-byte area in main storage is 



RPG 

Program 

Begin 




10 DTF Table Address Pointers 




4 Bytes Each 



DTF 



CCB 




Figure 4.11. Using RPG Pointers to DTF 



initialized by RPG to indicate what caused 
the halt zero. This area is located at a 
displacement of X'llC* from the beginning 
of the RPG object program. Figure 4.12 
shows the possible contents of the 7-byte 
halt zero analysis area. 



CAUSES OF A HALT ZERO CONDITION 



The object program: 

• Read an input record that was not 
defined on the Input Specifications 
sheet (columns 21-41). 
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j Displacements in Hexadecimal From Register 3 



h 



Condition That Turned HO On 



Initialized on or is on due to programmer request 

Invalid chaining request 

Undefined record type 

Collating sequence error (matching records) 

Record sequence error (predetermined sequence) 

DAM (record not found) 

DAM (data check) 

DAM (wrong length record) 

ISAM (invalid key length) 

(DASD error) 

(wrong length record) 

(illegal EOF — within limits) 

(duplicate record) 

(no record found) 



ISAM 
ISAM 
ISAM 
ISAM 
ISAM 



(A) = Chaining identifier 

(B) = Address of IORB 

(C) = Address of DTF table 
N/A = Not applicable 



Figure 4.12. Halt Indicator (HO) Analysis Aid 



lie 


120 121 122 | 
Resulting Byte Combina-j 


"T 


.-L_— — — _— .L 


tions Set (Hexadecimal) j 


| N/A | 00 | 00 | 00 | 


| (A) 


02 | N/A j N/A | 


\ (B) 


10 | N/A j N/A j 


j N/A 


04 | N/A | N/A j 


j N/A 


08 j N/A | N/A j 


| (C) 


N/A j 80 j N/A | 


| (C) 


N/A | 40 j N/A j 


| (C) 


N/A j 20 j N/A j 


| (B) 


N/A | N/A | FF j 


| (C) 


N/A j N/A j 80 j 


| (C) 


N/A | N/A | 40 | 


| (C) 


N/A | N/A | 20 j 


| (C) 


N/A | N/A j 04 j 


| (C) 


N/A j N/A | 10 j 






All Files 



1 



DAM Files Only — 

ISFMS Files Only ' 



• Found an input record out of the 
predetermined sequence of card type 
specified by the entry in Sequence 
(columns 15-16) on the Input 
Specifications sheet. 

• Found an input record out of sequence 
when the entry in Matching Fields 
(columns 61-62) on the Input 
Specifications sheet was used for 
sequence checking a single input file. 

• Encountered a chaining field in the 
chaining file that does not appear in 
the chained file during random 
processing of multiple input files. 

• Did not find a record with the correct 
key at the designated track address 
during random processing by record key 
of a DAM file. 

• Did not find the record key that 
designates the lower limit (obtained 
from the RAF) during sequential 
processing between limits of an indexed 
sequential file. 

• Found a wrong length record during 
processing of an indexed sequential 
file. 

• Found an invalid length record (zero or 
too long) during random processing by 



record identification of a file on a 
DASD. 



Found a difference between the key 
length of a DASD record in an indexed 
sequential file and the length as 
specified in Length of Record Address 
Field (columns 29-30) on the File 
Description Specifications sheet during 
processing with RAF support (random, 
ADDROUT, or between limits) . 



Found a difference between the key 
length in the chained indexed 
sequential file and the length as 
specified (columns 44-51) on the Input 
Specifications sheet during chaining of 
multiple input files. 

Encountered a data check on the DASD 
during random processing of a DAM file. 

Encountered a DASD error during 
sequential or random processing of an 
indexed sequential file . 



Note ; Unless the HO indicator is turned 
off by a SETOF Operation entry on the 
Calculation Specifications sheet, the 
program terminates before the next input 
record is read. 
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SAMPLE PROGRAM LISTING 






00S/360 


•RPC 


•V2. 


LO 






RPGSP 






03/22/67 


PAGE 0001 




00 


000 


H 
















RPG001 


001 


01 


010 


F INPUT 


IPE F 80 80 




REA040 SYSIPT 




RPG002 


002 


01 


020 


FOUTPUT 





V 132 132 


OF 


PRINTERSYSLST 




RPG003 


009 


01 


010 


I INPUT 


AA 


01 1 l- 










RPG004 


004 


01 


020 


I 












8 29 NAME 




RPG005 


005 


01 


030 


I 












30 310M0NTH 




RPG006 


006 


01 


040 


I 












32 330DAY 




RPG007 


007 


01 


050 


I 












34 380INVN0 




RPG008 


008 


01 


060 


I 












39 430CUSTN0L1 


RPG009 


009 


01 


070 


I 












44 450STATE 




RPG010 


010 


01 


080 


I 












46 480C1TY 




RPG011 


Oil 


01 


090 


I 












74 802 INVAMT 




RPG012 


012 


01 


010 


C 


01 




INVAHT A00 


TOTAL 


TOTAL 72 




RPQ013 


013 


01 


020 


c 


01 




INVAMT ADO 


GRPTOT 


GRPTOT 72 




RPG014 


014 


01 


010 


00UTPUT 


H 


201 IP 










RPG015 


015 


01 


020 







OR 


OF 










RPG016 


016 


01 


030 













53 


• A C C 


U N T S R' 


RPG017 


017 


01 


040 













77 


• E C E I V A B 


L E RE' 


RPG018 


018 


01 


050 













88 


•G I S T E R' 




RPG019 


019 


01 


060 







H 


I IP 










RPG020 


020 


01 


070 







OR 


OF 










RPG021 


021 


01 


080 













25 


•CUSTOMER' 




RPG022 


022 


01 


090 













80 


•LOCATION 


INVOICE* 


RPG023 


023 


01 


100 













109 


•INVOICE DATE 


INVOICE 1 


RPG024 


024 


01 


110 







H 


2 IP 










RPG025 


025 


01 


120 







OR 


OF 










RPG026 


026 


01 


130 













42 


•NUMBER 


CUSTOMER • 


RPG027 


027 


01 


140 













46 


•NAME* 




RPG028 


028 


01 


150 













79 


• STATE CITY 


NUMBER' 


RPG029 


029 


01 


160 













108 


■ MO OAY 


AMOUNT" 


RPG030 


030 


02 


010 







D 


2 01 










RPG031 


031 


02 


020 











CUSTNOZ 


23 






RPG032 


032 


02 


030 











NAME 


53 






RPG033 


033 


02 


040 











STATE I 


59 






RPG034 


034 


02 


050 











CITY I 


67 






RPG035 


035 


02 


060 











INVNO I 


79 






RPG036 


036 


02 


070 











MONTH I 


90 






RPG037 


037 


02 


080 











OAY £ 


96 






RPG038 


038 


02 


090 











INVAMT 


109 


•* , 0. • 




RPG039 


039 


02 


100 







T 


2 LI 










RPG040 


040 


02 


110 











GRPTOT B 109 


•$ , 0. • 




RPG041 


041 


02 


120 













110 


• •• 




RPG042 


042 


02 


130 







T 


2 LR 










RPG043 


043 


02 


140 











TOTAL 


109 


•* , 0. • 




RPG044 


044 


02 


150 













HI 


• ••• 




RPG045 






N) 


»* 


*r 


H« 


ON 


U5 




C 




H 


o 


fl> 


O 




05 


* 


03 


H 


*< 


CO 


CO 


• 


ft 




(t> 




3 


JO 




-^ 


H3 


Q 


H 







CO 


ua 


OJ 


H 


3 


Q) 


^ 


a 


H 


§ 


ro 


fl> 




H 


•X) 




h 


to" 


o 




iQ 


C7i 


n 


d 


(U 


H» 


s* 


Oj 




<D 


«^ 




*ti 




0> 



O 



SAMPLE PROGRAM LISTING (CONTINUED) 








OOS/360«RPG*V2.LO 


RPGSP1 

SYMBOL 


TABLES 


03/22/67 


PAGE 


0002 




RESULTING INDICATORS 














AOORESS RI AOORESS RI 


ADDRESS RI ADDRESS 


RI ADDRESS RI ADDRESS 


RI 


AOORESS 


RI 


000011 OF 000014 IP 


000015 LR 000016 


00 000017 01 00007A 


LO 


00007B 


LI 


000085 HO 000086 HI 


000087 H2 000088 


H3 000089 H4 00008A 


H5 


00008B 


H6 


00008C H7 000080 H8 


00008E H9 












FIELD NAMES 














ADDRESS FIELD ADDRESS 


FIELD ADDRESS FIELD ADDRESS FIELD 


AOORESS 


FIELD 




000123 NAME 000139 


MONTH 0001 3B DAY 


000130 INVNO 


000140 


CUSTNO 




000143 STATE 000145 


CITY 000147 INVAMT 00014B TOTAL 


00014F 


GRPTOT 




LITERALS 














AOORESS LITERAL 


ADDRESS LITERAL 




ADDRESS LITERAL 








000153 ACCOUNTS 


R 00016B E C E I V A 


B L E RE 


000183 G I S T E 


R 






00018E CUSTOMER' 


000196 LOCATION 


INVOICE 










LITERALS 














AOORESS LITERAL 


AOORESS LITERAL 




AOORESS LITERAL 








0001AC INVOICE DATE INVOICE 0001C3 NUMBER 


CUSTOMER 


0001DB NAME 








0001DF STATE CITY NUMBER 0001F7 MO DAY 


AMOUNT 










LITERALS 














AOORESS LITERAL 


AOORESS LITERAL 




ADDRESS LITERAL 








00020C — , — /. — 


000217 • 

MEMORY MAP 




000218 •• 








INPUT/OUTPUT INTERCEPT 




000220 










TABLE IINPUT ANO OUTPUT) 




00021C 










DETERMINE RECORD TYPE 




000464 










DATA SPECIFICATION 




000248 










GET INPUT RECORD 




00078C 










DETAIL CALCULATIONS 




000904 










TOTAL CALCULATIONS 




000958 










OETAIL LINES 




000AD2 










TOTAL LINES 




00096C 










INPUT/OUTPUT REQUEST BLOCKS POINTER 


00126C 










LOCATION OF OTF TABLE POINTERS 




000D18 














H 
0) 

O 
H 

3 



SAMPLE PROGRAM LISTING (CONTINUED) 



o 



DOS/36O»RPG»V2.L0 

INPUT/OUTPUT INTERFACE ROUTINES 

WORK AREA POINTER 

OVERFLOW BYPASS 

CONTROL LEVEL 

TABLEIASSEMBLE 4) 

TEST ZONE (BCD) 

OVERFLOW LINES 

LINKAGE PROGRAM 



RPGSP1 



PAGE 0003 



0000E0 
001574 
OOOACA 
00063C 
OOOBAC 
0012AC 
0009EA 
0013E4 



PROGRAM LENGTH 001699 
•END OF COMPILATION* 



ro 



03 






SAMPLE PROGRAM LINKAGE EDITOR MAP 



w 
►d 
Q 

CO 

9 



*d 

h 

3 



JOB RPGSP1 

ACTION TAKLN 

LIST 

LIST 

LIST FNTRV 



03/. >/67 DISK LINKAGE EOITOR DIAGNOSTIC OF INPUT 



MAP 
INCLUDE 
INCLUDE 



IJCFCIZO 
IJDFYPZZ 



RPG00114 
RPG00115 



O 



01722/67 PHASE XFR-AD LOCURE HICORE DSK-AD 
PHASF»»« 0033E4 002000 00378B 25 6 I 



ESD TYPE 


LABEL 


LOADED 


REL-FR 


CSECT 


RPG001 


002000 


002000 


CSECT 


IJCFCIZO 


0036A0 


0036A0 


• ENTRY 


IJCFZIZO 


0036A0 




CSECT 


IJDFYPZZ 


003710 


003710 


• ENTRY 


IJDFYZZZ 


003710 





(D 



SAMPLE PROGRAM S OUTPUT 



en 



h 
o 

3 



CUSTOMER 
NUMBER 



10712 



11315 
11315 



11897 



18530 



ACCOUNTS RECEIVABLE REGISTER 



CUSTOMER NAME 
AMALGAMATED CORP 



BROWN WHOLESALE 
BROWN WHOLESALE 



FARM IMPLEMENTS 



LOCATION 
STATE CITY 



33 



30 
30 



231 
231 



BLACK OIL 



INVOICE 
NUMBER 



11603 



12324 
99588 



10901 



11509 



NVOICE 
MO 


DATE 
DAY 


INVOICE 
AMOUNT 


11 


10 1 


389.25 
389. 25* 


12 


28 1 


802.08 


12 


14 1 


, 261.17 
k 1.063.25* 


10 
11 


18 i 
8 


k 27.63 
k 27.63» 
k 592.95 



DUMP TAKEN HERE 



(D 



W 
(1) 
3 
>0 
H 
(D 

*3 
H 


H 
0) 

3 



H 
ff 



o 













CORE DUMP 














RPGSP1 




03/22/67 




PACE I 
















CR 0-7 


0000354C 


00003544 


000001E0 


00002000 


00003000 


00004000 


00005000 


00006000 










GR 8-F 


50002B90 


00003574 


00000001 


0000208E 


00002085 


400033E6 


50003452 


00002A02 










002000 


05805808 


000607F0 


000033E4 


00000000 


00000000 


OOOOFOOO 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


002030 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


00000000 


002060 


00000000 


00000000 


0000000 


00000000 


00000000 


00000000 


OOOOFOOO 


00000000 


00000000 


OOFOOOOO 


00000000 


00000000 


002090 


00000000 


00002220 


00002000 


00002000 


0000221C 


00002000 


00002000 


00002464 


00002248 


0000278C 


00002904 


00002958 


0020C0 


00002A02 


0000296C 


0000326C 


00002D18 


00002DEO 


00002000 


00002000 


00002000 


00002000 


00006000 


00003574 


00007000 


0020FO 


00008000 


00009000 


OOOOAOOO 


00002ACA 


00002000 


00002000 


0000263C 


00002BAC 


000032AC 


000029EA 


00000000 


0000326C 


002120 


100000C4 


CIE3C140 


C3C1D9C4 


40404040 


40404040 


40404040 


40000C00 


OCOOOOOC 


OOOOOCOO 


OCOOOCOO 


00000C02 


07308C00 


002150 


59295C40 


40404040 


40C140C3 


40C34006 


40E440D5 


40E340E2 


4040D940 


C540C340 


C540C940 


E540C140 


C2400340 


C5404009 


002180 


40C540C7 


40C940E2 


40E340C5 


4009C3E4 


E2E3D6D4 


C50903D6 


C3C1E3C9 


D6054040 


40404040 


40C9D5E5 


D6C9C3C5 


C905E506 


0021B0 


C9C3C540 


C4C1E3C5 


40404040 


C9D5E5D6 


C9C3C505 


E4D4C2C5 


D9404040 


40404040 


4040C3E4 


E2E306D4 


C5D94005 


C104C540 


0021EO 


E2E3C1E3 


C5404040 


C3C9E3E8 


40404040 


4005E4D4 


C2C5D940 


D4D64040 


4040C4C1 


E8404 040 


4040C104 


D6E405E3 


40402020 


002210 


6B202021 


4B20205C 


5C5CO00O 


07FE0000 


05EO50C0 


F01E18C0 


D500F022 


C00058C0 


F01E58F3 


00980 78F 


58F300D0 


07FF0000 


002240 


000032AC 


4000022C 


05805810 


803E1211 


078E5881 


00041288 


078E1A83 


589300C8 


4A910002 


58290000 


41900FFF 


41989001 


002270 


05F847F0 


F09647F0 


F0C647F0 


F0DE47FO 


F1184 7F0 


F1240700 


80002720 


41AC0002 


41900003 


9500 AOOO 


4780F034 


D201F032 


0022A0 


A0009200 


000041AA 


00024690 


F0229500 


C0064780 


F05444B0 


F0904770 


F05441CC 


000647F0 


F07C41CC 


00029500 


C0004780 


002200 


F06844B0 


F0904720 


F07C9500 


C0024780 


F08644B0 


F09047A0 


F08641CC 


0002D201 


F084C000 


96F00000 


41980FFF 


41990001 


002300 


07FAF800 


10001000 


44B0F0C0 


189B8890 


00041A19 


91001000 


4710F0B2 


94F01000 


960C1000 


1B1918A9 


41980FFF 


41990001 


002330 


07FCF200 


1000A000 


180C45C0 


F096189A 


18C088B0 


000489B0 


000416B9 


47F0F01A 


189B8R90 


0004 I AA9 


D200F105 


A0009100 


002360 


A00O471O 


F0FC960F 


A00094FC 


A0001BA9 


44B0F112 


1AA99200 


A000419R 


0FFF4199 


000107FC 


F8001000 


A000180C 


45C0F00E 


002390 


18C047F0 


F01AD201 


F12CC002 


92000000 


95401000 


4770C004 


41AC0004 


12BB4780 


F07806B0 


44B0F154 


4780F078 


41980FFF 


002 3C0 


41990001 


07FAD500 


10001001 


D2153123 


20074110 


313941A0 


201D41B0 


001145CF 


00004 110 


313B4U0 


201F41B0 


001145CF 


002 3F0 


00004110 


313041AO 


202141B0 


002445CF 


00004110 


314041A0 


202641B0 


002445CF 


00004110 


314341A0 


202B41B0 


001145CF 


002420 


00004110 


314541A0 


202041B0 


001245CF 


00004110 


314741A0 


204 941B0 


003645CF 


00000 7FE 


18530C40 


185 30C40 


F2249000 


002450 


202694FC 


900245BC 


000007FE 


92003017 


07FE4110 


5 80 300 E 8 


50f 00004 


50800008 


58A300B4 


582A0008 


1A2341B0 


201A4210 


002480 


F027DC00 


F0272000 


41A00000 


581AB000 


1A135893 


00C84A91 


000641F0 


F06605EF 


58F1000C 


12FF4780 


E0181AF3 


58C 30108 


0024B0 


58AC0OOC 


IAA305EF 


58AJO0B0 


501A0040 


58ED0004 


588D0008 


07FE50EO 


00005829 


00000705 


F01AF01A 


07031010 


10109047 



o 

cr 

c 

H- 

3 

CO 



to 

en 



c 
•i 



U) 



HI 
en 

w 

I 



o 

H 

3 



O 



o 











CORE DUMP (CONTINUED) 












RPGSPl 




03/22/67 




PAGE 2 
















0024E0 


O02805EI 


ooooouoo 


01009847 


D028188E 


18909500 


80044780 


80260200 


900F8004 


9204900E 


58F30094 


05EF5890 


80481A93 


002510 


47F0804C 


41800FFF 


41548001 


41658001 


41768001 


41878001 


07F4B006 


00000448 


58F08000 


12FF4780 


806ED703 


80608060 


002540 


1AF305EF 


B0044040 


06028060 


80604740 


8076960F 


100047F0 


81369045 


D0284140 


00034150 


00441BFF 


180943F4 


805F12FF 


002510 


478080C8 


06F04450 


81484790 


80C0182F 


41220001 


88200001 


89200004 


16F244F0 


814288F0 


0004419F 


900094FC 


90001B9F 


0025AO 


47F080C4 


44F0813C 


419F9001 


44508148 


478080DA 


069094FC 


90004199 


00018850 


0001 18CB 


18BA4640 


80869845 


D0281B90 


0025D0 


06901880 


47F08100 


181B58F3 


0U805EF 


581D0024 


91F01000 


47C0812C 


91041014 


47808UC 


4490814C 


47B0812C 


47F08124 


&02600 


4490814C 


47U0812C 


92F03085 


92043120 


92F01000 


44908152 


189058ED 


00OCO7FE 


D2009000 


C000F200 


9000COOO 


91008063 


002610 


D500B000 


10180200 


101RB000 


O5O2A00O 


90004780 


B0000202 


A0009000 


02003078 


8U407FB 


D5FFA003 


90034780 


B00002FF 


002660 


A0039003 


0201307B 


811407FB 


05FFA003 


90034780 


B000D2FF 


A0039003 


0202307B 


811407FB 


05FFA003 


90034780 


B000D2FF 


002690 


A0039003 


D203307B 


811407FB 


D5FFA003 


900 34 780 


B000D2FF 


A0039003 


D20430 7B 


811407FB 


05FFA003 


90034780 


B000D2FF 


0026CO 


A0039003 


D205307B 


811407FB 


05FFA003 


90034780 


B00002FF 


A0039003 


D20630 7B 


B11407FB 


D5FFA003 


90034780 


B000D2FF 


0026F0 


A0039003 


D207307B 


811407FB 


D5FFA003 


90034780 


B000D2FF 


A0039003 


D208307B 


8U407FB 


B0080000 


00000444 


4511001C 


002720 


BF 180000 


000003CC 


00002085 


00000000 


E2C9C7D5 


00000100 


454E0030 


58C30110 


43902000 


41A00060 


05BC4770 


404041 AO 


002750 


30179201 


E00496F0 


A00050A1 


000847F0 


4030B00A 


000003CC 


0000044C 


02031004 


4028D203 


100C402C 


47F0E006 


41A30085 


002780 


50A 10008 


9201E004 


4 7F0E006 


058047F0 


800EB00A 


E7D7D9C5 


0000045C 


18105803 


0OE8501D 


000850EO 


00040708 


307B307B 


002 7B0 


47F08126 


58C300C8 


4AC10002 


582C0000 


5890807A 


1A9358A1 


000896F0 


A0009585 


100B4 770 


805050C3 


011C9210 


312058A3 


0027E0 


00R0501A 


004C58F1 


000C12FF 


47808070 


1AF358C3 


010858AC 


00DCIAA3 


05EF58ED 


00045 800 


000807FE 


00000448 


580300C8 


002810 


4A0 10006 


189050ED 


001858F0 


800A1AF3 


05FF9200 


900E58F3 


009405EF 


95F03085 


477080B4 


58AJ00B0 


D703A040 


A04047F0 


002840 


80709522 


90134770 


80FA58ED 


00184111 


000492F0 


10019108 


1014078F 


48C0816A 


46C080E4 


96F03015 


D208307B 


811447F0 


002870 


807040CO 


B16A07FE 


50800014 


58F300AC 


41FF0066 


05EF5880 


001458A1 


00089200 


A00058EO 


001847F0 


80264770 


802607FE 


0028AO 


800CF0F0 


F0F0F0F0 


FOFOFOFO 


0700B006 


0000071C 


58108122 


1A1345E0 


807E47F0 


800658ED 


001C95F0 


1001077E 


92F08164 


002800 


95F08165 


47808006 


41F000AA 


40F0817E 


95B08U2 


078E5810 


816647F0 


82300700 


BOOCOOOO 


00000000 


00010004 


41F08180 


002900 


92A305EF 
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Debugging PL/I Programs 



PL/I is made up of subroutines, a control 
program, and a mainline routine. The 
mainline routine manipulates the data to 
develop information for a particular 
application. The control program 
initializes the mainline routine. It also 
provides linkage to subroutines to get the 
data from a file for use by the mainline 
routine and to create new files of updated 
information. The control program uses 
transients much the same as the supervisor, 
and it has its own transient area (Figure 
4.14). 



The PL/I storage areas important for 
debugging purposes are: static storage, 
dynamic storage area (DSA) , and library 
work space. Figure 4.15 shows the contents 
of these areas, when assigned , pointers to 
these areas, and where each area is 
located. Static storage contains all of 
the information needed by a PL/I program; 
literals, address constants, control blocks 
and block descriptions. Figure 4.16 shows 
a list of subroutines that are moved into 
the control program to provide needed 
functions to the mainline. 



SYSSUP 

Intercepts Program Check. Passes 
Control to PL/I STXIT PC Locatfon 



MAINLINE 



CONTROL PROGRAM 



Initialization (Prologue) 
GO TO External Name 
OPEN/CLOSE 
READ, WRITE, Etc. 
END. (MAIN), STOP 



Miscellaneous Subroutines 
Such as: 
* I/O Transmitters 

Conversion Routines 
Built-in Functions 



* 



+ • 



Initialization Routine 



• GO TO Routine 

(Return is to External Name) 

• OPEN/CLOSE Routines 

Call $ Transients 

• SIGNAL Routine Handles 
Exceptional Conditions and 
Issues Messages 

• STOP Routine Calls $ 
Transient for Automatic 
Closing of Files and EOJ 

• Interrupt Handler Usually 
Calls $ Transient. 
Return is Conditional 



$ Transient Area 
May Call $$B Transients 



Figure 4.14. PL/I Program Structure 
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Contents 






When Assigned-- ■> 



| Static 
j. 

Literals, Address 
Constants f Control 
Blocks , Block 
Descriptions . 
j. 



| Dynamic 



How Pointed to — -> 



Where located — ■> 



At Compile Time - 
Determine size, 
contents and 
location. 



Register 12 when 
procedure is active. 



Doubleword boundary 
immediately follow- 
ing procedure. 



Linkage register and 
AUTOMATIC data save 
areas. 



j Library Work Space 
+ 



-H 



At Compile Time - 
Determine size and 
location of data 
within DSA. 

At Object Time - 
Determine actual 
location when pro- 
cedure is activated. 

Register 13 when pro- 
cedure is active. 
Register 11 Used with 
Register 10 nested pro- 
cedures . 

Doubleword boundary 
immediately following 
highest core location 
(taken from COMRG) . 






Register save area and 
work area for PL/I 
subroutines. 



H 



At Linkage Editor 
Time - Part of PL/I 
control program is 
AUTOLINKed regardless 
of need. 



Register 13 when sub- 
routine is active. 



IJKZWSA from linkage 
editor map. 



Figure 4.15. PL/I Storage Areas 
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Part of -the PL/I prologue moves a list of subroutine address constants from static 
storage to an entry point table within the PL/I control program. 

This table contains 16 positional entries as follows: 

Displacement j Position j Subroutine j Description 



H 



Source 

ft 
8 
C 

10 

lft 
18 
1C 
20 

Target 

ft 
8 
C 

10 



Sysfiles 
14 
18 



IJKVBCM (28) 

IJKVTCM (29) 

IJKVPCM (2A) 

IJKVFCM (2B) 

IJKVECM (2C) 

IJKVGIM (2D) 

IJKVIGM (2E) 

IJKTSTR (2F) 

IJKTLCM (30) 



IJKVCBM (31) 

IJKVCTM (32) 

IJKVCPM (33) 

IJKVCFM (3ft) 

IJKVCEM (35) 



IJKSYSI (36) 
IJKSYSA (37) 



Converts fixed binary to intermediate. 

Converts float to intermediate. 

Converts fixed decimal to intermediate. 

Converts numeric field float to 

intermediate . 

Converts 'E* or •F* format to 

intermediate . 

Converts character string to bit string. 

Converts bit string to character string. 

X format item, PAGE, SKIP, 

LINE, COLUMN 



Converts intermediate to fixed binary. 

Converts intermediate to float. 

Converts intermediate to fixed decimal. 

Converts intermediate to numeric field 

float. 

Converts intermediate to 'E* or , F f 



format. 



SYSIN 
SYSPRINT 









Figure ft. 16. Entry Point Table 
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Figure 4.17 shows the layout of core 
storage at object time. The PL/I problem 
procedure (mainline coding) , the control 
program, and the library subroutines are 
shown. These areas can be located by using 
the linkage editor map. 



Figure 4.17 also shows the dynamic 
storage areas that are loaded directly 
behind the rest of the PL/I program. 
Because they are not on the linkage editor 
map, the programmer must look in bytes 
40-13 (decimal) of the system 
communications region and find the 
high-core address of the program to locate 
the first DSA. Remember that the 
communication region has two ending address 
entries (one entry for the last phase 
loaded and another entry for the ending 
address of the program) . The ending 
address of the program is the entry the 
programmer must use. 



Hardware Area 



Supervisor Transient Areas 



DTF - Appendages 
DTFs and Buffers 
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DSAs 



Figure 4.17. Object Time Core Usage 
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Figure 4.18. Library Work Space 



Figure 4.18 shows an example of library 
storage that contains work space, save 
areas, and pointers to the DSA (chain 
back) . A communications region follows the 
work areas. Figure 4.19 shows some of the 
information stored in this area. 
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Figure 4.19. Communications Area Switches 



Figure 4.20 shows the layout of the DSA. 
Each procedure has a DSA containing the 
following information: 



1. The condition of the DSA, indicated by 
the flag bytes. 



2. A block description in static storage 
pointed to by the last 3 bytes of the 
first word (see Figure 4.21). 



The chain forward and back addresses 
that allow the programmer to follow 
the program flow from procedure to 
procedure. 
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Figure 4.20. Dummy DSA and DSA Layout 



A dummy DSA is built to indicate the 
beginning of a chain of DSAs when backward 
chaining. Figure 4.20 shows the dummy DSA. 
Figure 4.22 gives an example of DSA 
chaining . 
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Figure ft. 21. Block Description 
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Figure 4.22. DSA Chaining 



When debugging PL/I problem programs, 
the programmer must know how to locate the 
DTF tables. In PL/I, the DTF table has an 
appendage that precedes the DTF proper and 
contains a pointer to the DTF (Figure 
4.23). The appendage can easily be found 
because it is listed as the linkage editor 
map by filename. Figure 4.24 shows the 
format of the DTF used by PL/I. A sample 
program, linkage editor map and core dump 
are included in Figure 4.25 to aid the 
programmer in debugging his PL/I problem 
program. 
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00- Regional 1 
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A L3(Disk Address Routine) 
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Key Length 00 - Regional 1 
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M 
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Figure 4.23. PL/I Consecutive File DTF-A 
Appendage 



Figure 4.24. PL/I Regional File DTF-A 



SUMMARY OF PL/I DEBUGGING AIDS 



1. Register 13 (at the start of the dump) 
points to a library work space or 
dynamic storage area. 

2. Always chain back from the library 
work space or DSA to find the active 
DSAs. 

3. The DSA (main) can be located by using 
the value contained in the COMREG at a 
decimal displacement 40-43. Adjust 
this value to a doubleword boundary. 

4. If the PL/I error signaled is a 
program check, use the PSW and 
registers located in IJKZWSI. This 
area has a PSW followed by the 
registers stored R0 through R15. 



5. The PL/I control program intercepts 
and tries to handle all errors except 
machine checks. The control program 
issues a PL/I error message, and a 
main storage dump is executed from the 
control program. Following the dump, 
PL/I closes all files. If a printed 
output is produced at the time of 
error, PL/I prints the last item after 
the dump is taken. This gives the 
programmer a starting point to the 
correct area of the failure. 



6. PL/I program check error message codes 
11 through IE are the same as the 
interrupt codes 01 through 0E on the 
IBM S/360 Reference Data card, 
GX20-1703. 
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PL/I error messages point to the 
approximate location where an error 
occurred. 



8. The name of the last PL/I transient 
fetched is at the label • CURS'. To 
find the labels CIJKS and DISPL (item 
9 ) , use register 13 and the chain back 
fields to locate the dummy DSA 
(identified by its first byte being 
zero) . Scan backward approximately 
four fullwords and locate X'0A04* 
(load instruction) . Following the 
load is X'^Flxxxx', which is labeled 
DISPL. Immediately following this is 
CIJKS. (PL/I (D) transients are of 
the format 'IJKSxx • . DISPL and CIJKS 
are in the routine IJKSZCA.) 



The branch instruction that activates 
a transient just fetched is at the 
label ' DISPL*. 



14. The following language aids are useful 
in debugging both source and object 
problems . 

a. Dyndump 

b. Display 

c. Display using the reply option (to 
halt a program) 

d. Null labels 

e. Signal statement (to force dump) 

Note : In multiphase programs, the first 
four characters of the phase names must be 
identical and unique to the program. If 
they are not, either the DSA is overlaid or 
the DSA may not fit into the available 
core. 



HANDLING COMPILE TIME ABORTS 



10. To locate the current file, look in 
'WCFL* in the library work space. 
This contains a request code and 
pointer to a DTF-A. To find WCFL, use 
the label IJKZWSI in the linkage 
editor map. Start in the core dump at 
that location and scan backward until 
you locate a fullword beginning with 
X'FE*. The fullword immediately 
preceding this is the current file 
address, labeled WCFL. (WCFL is in 
the routine IJKSZCA. ) 

11. The first word of any DTF-A points to 
a logical IOCS DTF. 

12. The linkage editor map has a CSECT for 
each DTF-A. 

13. PL/I register usage is as follows: 

a. The instruction flow base 
registers in a procedure are 13 
(11 and 10) for dynamic storage 
and 12 for static storage. 

b. The data accessing base registers 
in a procedure are 13 (11 and 10) 
for dynamic storage and 12 for 
static storage. 

c. The instruction flow base 
registers in a PL/I subroutine are 
15 and 12. 

d. The data accessing base registers 
in a PL/I subroutine are 13 and 
11. 

e. The parameter passing registers 
are through 5. (Register 1 is 
the most commonly used.) 



The following pointers within the control 
program indicate how far the compiler 
progressed before the abort condition 
occurred: 

1. Register 12 points to the start of the 
control program and is used as the 
base register. 

2. The KSAVE1 area contains return 
registers in the following order: 

R 14 - points to last active routine 
R 15 
R 
R 1 
R 2 

To locate KSAVE1, add X'DB* to the 
contents of register 12. 

3. The K5PH area (8 bytes) contains the 
name of the phase now in storage. The 
phase name is constructed in the 
following manner: 

PL/Ixxxx 

The last four bytes xxxx contain 
the actual phase identifier such as 
D75. To locate K5PH, add X , 284 f to 
the contents of register 12. 

Exceptions : D00, D05, D10. During these 
three phases, the phase name can be located 
by adding X* 108* to the contents of 
register 12. If K5PH contains phase C95, 
the actual phase may be either C95 or Dll. 

4. IJKZWSI is valid only if a PSW has 
been stored there. 
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CALL REPEAT (CTR), . 


OOOOAE 


90EE 0058 






STM 


E,E,X'058' (D) 





to 

ON 

00 



o 

s 

CO 

•< 

CO 

(t 

B 

3 

9 









to 

01 



•US 



H 
•0 

t 



P 



o 
m 

+■» 
09 
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LOC. 


object cooe 




LABEL 


OP. 


OPERANDS 




0000B2 


1800 






LR 


0,0 




000084 


58F0 C06i» 






L 


F.N'0115* =V (REPEAT) 




O00OB8 


HI 10 00S8 






LA 


1,X*058*CD) REG 1 POINTS AT A (CTR^ 




OOOOBC 


05EF 






BALR 


E.F 




OOOOBE 


H7F0 905E 


GOTO. 


L'Olll' 


BC 


F.N'OIOB' GO TO READ 




00O0C2 


4110 C010 


END . . 


L*01,12* 


LA 


l.X'OlOMC) =A(INCARD) CLOSE FILE (INCARD),. 




0800C6 


S8F0 C048 






L 


F,N*0019' =V(IJKTCLM) 'CLOSE' 




OOOOCA 


05EF 






BALR 


E.F 




OOOOCC 


4110 CO 14 


END 1 . 


L'0113' 


LA 


1,X'014*(C) CLOSE FILE (OTCARD),. 




000000 


58 FO C048 






L 


F,N'0019' 




ooooou 

000006 


05EF 
5800 0004 






BALR 

L 


E.F 




D,X*004*ID) REG 13 = A (DUMMY DSA) 


TERMINATION 




OOOODA 


98EC OOOC 






LM 


E,C.X*00CMDJ REG 14 = A(STOP ROUTINE) 






OOOOOE 
OOOOEO 


07FE 






BCR 
END C 


F.E 




>F BLOCK 






OOOOEO 


0000300040005000 


L'FFFF' 
L'OOOU' 


STAT1 

DC 


PC ST0RAG4E 




X' 0000300040005 000* 


ADDRESS INCREMENTS USED WHEN DATA OR 




0000 EC 


60007000 
OOOOOOOO 




L'0006* 


DC 
DC 


X' 60007000' 


BRANCHING IS FURTHER THAN 4K FROM BASE REG 


X» OOOOOOOO* 






0000*0 


80 




I'OIID* 


DC 


X'80' 




0QO0F1 


000000 






DC 


VL3(N'0l00') 




OOOOFU 


80 




L'OIIE* 


DC 


X'80' 




0000F5 


000000 






DC 


VLSI N* 01 01*1 




00 OOF 8 


58 




L'OIIF* 


DC 


X'5B' READ INTO 




0000F9 


000000 






DC 


VL3*N*0100«) FILE ADDRESS 




0000 FC 


OOOOOOi* 8 






DC 


X '00000048' DATA LENGTH 




000 100 


OOOOOOOO 






DC 


X' OOOOOOOO' ADDRESS OF WORKAREA 




000 10U 


23 




L*0120* 


DC 


•X'23* 




000105 


000000 






DC 


VLSIN'OIOIM 




000108 


00000050 






DC 


X' 00000050* 




000 IOC 


OOOOOOOO 






DC 


X* OOOOOOOO* 




000110 


000800F8 




L'0116' 


DC 


X*000800F8* BLOCK DESCRIPTION 




0001 iu 


O0O0C002 




L'0182' 


DC 


A{N*8102') 




004) 1 18 


OA 






DC 


X*0A* 'ON' ENTRY 




000119 


000008 






DC 


VL3(N*O10O*) 




0001 1C 


80000000 






DC 


X* 80000000' 




000120 


OOOOOOOO 




L'0038* 


DC 


V<N*O038* > 




0&012U 






I • 0005' 


DC 


X" 




O0O12* 


8F 




L'0Q37' 


DC 


X'8F' ENTRY POINT TABLE BIT = 1 MEANS 'LAST ENTRY' 




000125 


OOOOOO 






DC 


VL3<N'0037') 




00)0*28 


OOOOOOOO 




L'OOJ.9* 


DC 


VtN'0019') 




O0012C 


OOOOOOOO 




L'0018* 


DC 


VI N* 0018') 




000 1 30 


80000000 




L*0016* 


DC 


VI N* 00 16') 




000 13U 


OOOOOOOO 




L • 1 1 • 


DC 


V(N'OOM') 




000138 


00008000 




L*0H4' 


DC 


V(N*0114M 




0001 3C 


00000002 




L'OHC 


DC 


A ( H* 1 02 • ) 




000140 


ooooooco 






DC 


X'OOOOOOCO* 2 BYTES - INVOCATION COUNT NEXT 2 BYTES 'GOTO' ADDR IN 'ON' ENTRY 




000 UU 


oooocooo 




L'Gl 15* 


DC 


V(N'0115' ) 




000 f»8 


OOC0000000000080 


L'0OO1' 


DC 


X' 0000000800000000 ' 




008150 


FFFFFFFFFFFFFFFF 


L'0002' 


DC 


X' FFFFFFFFFFFFFFFF' 



C 
h 
0> 



to 
en 



H 

H 

O 
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H 
rt 

en 
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OBJECT CODE 



O0F6FFFF 
OC 



LABEL 



L'OOOA* 
L'OOOB* 



OP. 

DC 
DC 
END 



OPERANDS 



X'OOFEFFFF' 
X'OC* 
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INCARD 


SD 


0001 


000000 


00009B 


IJCFZIZO 


ER 


0002 






IJKTXCF 


ER 


0003 






OTCARD 


SD 


0004 


000000 


OOOOFO 


IJCFZ0Z4 


ER 


0005 






STAHT 


SD 


0001 


000000 


000160 


INCARD 


ER 


0002 






OTCARD 


ER 


0003 






SUB I 


ER 


0004 






REPEAT 


ER 


0005 






IJKSZCA 


ER 


0006 






IJKSZCM 


ER 


0007 






IJKSZLM 


ER 


0008 






IJKTOPM 


ER 


0009 






IJKTCLM 


ER 


OOOA 






IJKSYSA 


ER 


OOOB 






I JKTCBM 


ER 


OOOC 







® 

cr 

p 

ua 

H« 

9 

> 

Qi 
0) 



to 

vO 
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/• EXAMPLE OF THREE EXTERNAL 


PROCEDURES PASSING 


PARAMETER */ 








/• THIS PROCEDURE ACCEPTS (CTR) 


ZEROES IT ON THE 


FIRST ENTRY */ 








/• THEN PASSES IT TO PROCEDURE 


•LAST' FOR INCREMENTING »/ 








/• ON SUBSEQUENT ENTRIES THIS PROCEDURE ONLY PASSES ?CTR) TO 'LAST */ 






1 


SUBl.. PROCEDURE (CTR),. 










2 


DECLARE 












CTR PICTURE •99999*,. 








3 


CT.. CTR'O,. 










4 


CL.. CALL LAST (CTR),. 










5 


RET.. RETURN,. 










6 


REPEAT.. ENTRY (CTR),. 










7 


CC. CALL LAST (CTR),. 










8 


R.. RETURN,. 










9 


END.. END,. 
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SYMBOL TABLE 


LISTING 








SUB1 

CTR 

CT 


0100 00 ENTRY 


ARITHM. DECIMAL 


FLOAT 6 


EXT 




0101 01 1 


PICTURE DECIMAL 


FIXED 5,0 PARAM. 


INT 




0102 01 I 


LABEL CONST. 




INT 




CL 

RET 

REPEAT 


0103 01 1 


LABEL CONST. 




INT 




0104 01 1 


LABEL CONST. 




INT 




0105 01 ENTRY 


ARITHM. DECIMAL 


FLOAT 6 


FXT 




cc 


0106 01 1 


LABEL CONST. 




INT 




0107 01 1 


LABEL CONST. 




INT 




END 
LAST 


0108 01 1 


LABEL CONST. 




ITJT 




0109 01 1 ENTRY 


ARITHM. BINARY 


FTXED 15 


E^T 
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INTERNAL NAME OFFSET TYPE 


MODULE OFFSET 


OFFSET TABLE 








0100 0014 STATIC 


O00ODC 










0101 0058 AUTOMATIC 












0105 0018 STATIC 


00OOE0 










0109 0020 STATIC 


0000E8 
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LOC. 


OBJECT CODE 


LABEL 
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OPERANDS 




000000 






L 


0100* 


BEGIN 


OF BLOCK 01 




000000 


90EC OOOC 








STM 


EtC.X'OOCMD) 




000004 


45E0 FOOC 








BAL 


E.X'OOCMF) 




000008 


000000C8 








OC 


AIN'FFFFM 




oooooc 


58C0 EOOO 








L 


CX'OOOME) 




000010 


189F 








LR 


9,F 




000012 


1831 








LR 


3,1 




000014 


58F0 COIC 








L 


F,N'00l2' 




000018 


05E0 








BALR 


E,0 




00001A 


41E0 EOOE 








LA 


E,X'OOEME) 




00001E 


051F 








BALR 


1,F 




000020 


03 








OC 


X'03» 




000021 


0000D8 








DC 


AL31N'010A») 




00002* 


00000100 








OC 


LENGTH OF OSA OF BLOCK 01 




C00028 


0203 0058 


3000 






MVC 


N«0101M04),X'000« (3) 




00002E 


0203 D050 


3004 






MVC 


X'050M04,D),X«00<»M3) 




000034 


5860 0058 




L 


0102' 


L 


b.N'OlOl' 




C00038 


D204 6000 


C03D 






MVC 


X'000M05,6),X'03DMC> 




C0003E 


5850 D058 




L 


0103* 


L 


S.N'OIOI' 




000042 


41E0 5000 








LA 


E,X»000M5) 




000046 


90EE 0060 








STM 


E,E,X , 060MD> 




00004A 


180D 








LR 


0,0 




U0004C 


58F0 C020 








L 


F,N»0109« 




000050 


4110 D060 








LA 


1,X«060MD) 




000054 


05EF 








8ALR 


E,F 




000056 


5800 0004 




l' 


0104* 


L 


D,X'004MO» 




00005A 


98EC DOOC 








LM 


E.C.X'OOCMD) 




00005E 


07FE 








BCR 


F,E 




000060 


47F0 909C 




L« 


0112* 


BC 


F.N'Olll' 




000064 


90EC OOOC 




L< 


0105' 


STM 


E,C,X'OOC'(D) 




000068 


45E0 FOOC 








BAL 


E.X'OOCMF) 




00006C 


00OO00C8 








DC 


A(N»FFFF« J 




000070 


58C0 EOOO 








L 


CX'OOOME) 




000074 


5890 C024 




L 


0114* 


L 


9,X»024MC) 




000078 


1831 








LR 


3,1 




00007A 


58F0 COIC 








L 


F,N»0012« 




00007E 


0700 








BCR 


0,0 




C00080 


05E0 








BALR 


E,0 




000082 


41E0 EOOE 








LA 


E,X«00EME) 




000086 


051F 








BALR 


l.F 




000088 


03 








DC 


X'03 1 




000089 


000008 








DC 


AL3(N»010AM 




00008C 


00000100 








DC 


LENGTH OF OSA OF BLOCK 01 




000090 


0203 0058 


3000 






MVC 


N'0l0lMO4»,X , O00M3) 




000096 


0203 0050 


3004 






MVC 


X»050M04,0),X«004M3) 




00009C 


5860 0058 




L' 


0106* 


L 


6,N«010l' 




OOOOAO 


41E0 6 COO 








LA 


E.X'OOO' (6) 




•J000A4 


90EE D060 








STM 


E,E,X'060« (OJ 




0000A8 


1800 








LR 


0,D 




OOOOAA 


58F0 C020 








L 


F,N«0109» 




COOOAE 
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LA 
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LOC. 


OBJECT CODE 


LABEL 


OP. OPERANDS 






000082 


05EF 




BALR EtF 






0000B4 


5800 0004 


L'0107 


L D,X , 004»<0> 






G00083 


98EC OOOC 




LM E.C.X'OOCMO) 






0000BC 


07FE 




BCR F,E 






OOOOBE 


5800 D004 


L'0108 


» L D,X'004MO) 






0000C2 


98EC OOOC 




LM E.CX'OOCMD) 






0000C6 


07FE 




BCR F,E 






0000C8 




L'FFFF 


END OF BLOCK 
STATIC STORAGE 






0000C8 


0000300040005000 
60007000 


L'0004 


• OC X , 0000300040005000« 
DC X»60007000» 






000004 


00000000 


L'0006 


DC X'OOOOOOOO' 






000008 


000C00F8 


L«010A 


DC X•O00CO0F8 , 






OOOOOC 


00000000 


L'0100 


DC AIN'OIOO') 






OOOOEO 


00000064 


L'0105 


DC A(N»0105») 






C000fc"4 




L»0005 


DC X»» 






000064 


ocoooooo 


L'0012 


DC V(N , 0012') 






0000E8 


00000000 


L'0109 


OC V(N»0109») 






OOOOEC 


ocoooooo 


L'01l3 


OC A(N«0100«) 






OCOOFO 


0000000000000000 


L'OOOl 


DC X« 0000000000000000* 






O0OQF8 


FFFFFFFFFFFFFFFF 


L'0002' 


OC X'FFFFFFFFFFFFFFFF' 






000100 


OOFFFFFF 


L'OOOA 


OC X'OOFEFFFF* 






000104 


OC 


L'OOOB' 


OC X'OC 






000105 


FOFOFOFOFO 


L«010C 


DC X'FOFOFOFOFO* 
ENO 
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SYMBOL 


TYPE ESIO ADOR LENGTH ESID EXTERNAL SYMBOL TABLE 






SUB1 


SO 0001 000000 000110 






REPEAT 


LO 000064 


0001 






LAST 


ER 0002 










IJKSZCN 


ER 0003 
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LENGTH OF OSA 


BLOCKTABLE 
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'• EXAMPLE OF THREE EXTERNAL PROCEDURES PASSING PARAMETER •/ 



/• EXAMPLE OF THREE EXTERNAL PROCEDURES PASSING PARAMETER »/ 
/• THIS PROCEDURE INCREMENTS FIELD (CTR) AND RETURNS IT VALUE »/ 
LAST.. PROCEDURE (CTR),. 
DECLARE 

CTR PICTURE •99999%. 
CT.. CTR*CTR*l,. 

RET.. RETURN,. 

END.. END,. 
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00 



LAST 

CTR 

CT 

RET 

END 



0100 


00 





0101 


01 


1 


0102 


01 


1 


0103 


01 


1 


0104 


01 


1 



ENTRY 



ARITHH. 


BINARY FIXED 


15 


EXT 


PICTURE 


DECIMAL FIXED 


5,0 


PARAM. INT 


LABEL 


CONST. 




INT 


LABEL 


CONST. 




INT 


LABEL 


CONST. 




INT 
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MODULE OFFSET 
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LOC. 


OBJECT CODE 


LA8EL 


OP. 


OPERANDS 




000000 






L»0100« 


BEGIN 


OF BLOCK 01 




000000 


90EC OOOC 






STM 


E.C.X'OOCMD) 




000004 


45E0 FOOC 






BAL 


E.X'OOCMF) 




000008 


00000080 






DC 


AIN'FFFF*) 




cooooc 


58C0 ECOO 






L 


C,X*000'(EI 




000010 


189F 






LR 


9,F 




000012 


1831 






LR 


3,1 




000014 


58F0 C018 






L 


F,N'0012« 




000018 


05E0 






BALR 


E,0 




00001A 


41E0 EOOE 






LA 


E.X'OOEME) 




00001E 


051F 






BALR 


ltF 




000020 


03 






DC 


X«03' 




000021 


000090 






OC 


AL3IN'0105M 




000024 


00000110 






OC 


LENGTH OF OSA OF BLOCK 01 




000028 


D203 0058 


3000 




MVC 


N'0101M04)tX»000 , (3) 




00002E 


0203 0050 


3004 




MVC 


X«050'(04 1 D),X , 004M3) 




000034 


5860 0058 




L'0102» 


L 


6,N'010l» 




000038 


F224 OOEO 


6000 




PACK 


X»0E0'I3,D),X'000 , (5 f 6) 




00003E 


F8F0 0060 


C035 




ZAP 


X«060M0,D),X»035»(1,C> 




000044 


FAF2 0060 


DOEO 




AP 


X«060M0,D),X«0E0M3,D) 




00004A 


F83F D0E8 


0060 




ZAP 


X«0E8M4,DI,X»060 , (0,D) 




000050 


92F9 C012 






MVI 


N«0105 , ♦2,X•F9 , 




000054 


F823 0070 


D0E8 




ZAP 


X'070»{3,D) t X»6E8M4,0) 




00005A 


92F8 C012 






MVI 


N'OIOS^^.X'FB* 




00005E 


5860 0058 






L 


6,N»0101' 




000062 


F342 6000 


0070 




UNPK 


X , 000M5,6),X»O7OM3,D) 




000068 


96F0 6004 






01 


X , 004*(6) t X*FO« 




00006C 


5800 0004 




L'0103* 


L 


0,X'004MD) 




000070 


98EC DOOC 






LM 


E,C,X»0OC»(DI 




000074 


07FE 






BCR 


F,E 




000076 


5800 D004 




L'0104' 


L 


0,X'004*(0) 




00007A 


98EC OOOC 






LM 


E.C.X'OOC'ID) 




00007E 


07FE 






BCR 


F.E 




000080 






L«FFFF» 
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C00080 


0000300040005000 


L , 0004' 


DC 


X' 0000300040005000' 






60007000 






DC 


X'60007000' 




C0008C 


00000000 




t'OOOfe' 1 


DC 


X'OOOOOOOO' 




000090 


000800F8 




L'0105' 


DC 


x^ooosooFe* 




000094 


00000000 




L'OIOO' 


OC 


AfN'OlOO' ) 




000098 






L'0005* 


DC 


X" 




000098 


00000000 




L'0012' 


nc 


VIN'OOIZ' ) 




00009C 








OS 


CL0004 




OOOOAO 


oooooooooooocooo 


L'OOOl' 


DC 


x • oocooooooooooooo • 




0000A8 


FFFFFFFFFFFFFFFF 


L'0002' 


DC 


X'FFFFFFFFFFFFFFF* * 




OOOOBO 


00FEFFFF 




L'OOOA' 


DC 


X'OOFEFFFF' 




0000B4 


OC 




L'OOOB' 


DC 


X'OC 
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L'0107* 
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END 
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JOB COMPILE 06/06/66 DISK LINKAGE EOITOR DIAGNOSTIC OF INPUT 



ACTION 


TAKEN 


MAP 


LIST 


PHASE CHAIN, S 


LIST 


AUTOLINK 


UCFZIZO 


LIST 


AUTOLINK 


UCFZ0Z4 


LIST 


AUTOLINK 


IJKSYSA 


LIST 


AUTOLINK 


IJJCP1N 


LIST 


AUTOLINK 


IJKSZCA 


LIST 


AUTOLINK 


IJKSZLM 


LIST 


AUTOLINK 


IJKTCBM 


LIST 


AUTOLINK 


IJKTXCF 


LIST 


ENTRY 
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Ej 
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hj 




0> 
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rt 




H 




to 









Ml 




H 




GO 



Ob/06/66 PHASE 


XFR-AD 


LOCQRE 


HI CORE DSK-AD 


ESD TYPE 


LABEL 


LOADED 


REL-FR 


CHAIN 


002190 


002000 


00307F 30 I 1 


CSECT 


INCARO 


002000 


002000 










CSECT 


IJCFZIZO 


0024B8 


0024B8 










CSECT 


IJKTXCF 


003008 


003008 










• ENTRY 


IJKTXCR 


003030 












• ENTRY 


IJKTXCW 


003042 












CSECT 


QTCARD 


002OA0 


0020AO 










CSECT 


IJCFZ0Z4 


002508 


002508 










CSECT 


STAHT 


002190 


002190 










CSECT 


SUB1 


0022F0 


0022F0 










ENTRY 


REPEAT 


002354 












CSECT 


IJKSZLM 


0020A0 


002DA0 










CSECT 


IJKSYSA 


0025B0 


0025B0 










CSECT 


IJKTCBM 


002DE0 


002DE0 










CSECT 


LAST 


002400 


002400 










CSECT 


IJKSZCN 


002758 


002758 










ENTRY 


IJKSZCA 


002988 












ENTRY 


IJKSZCH 


002990 












ENTRY 


IJKTOPM 


0029BA 












ENTRY 


IJKTCLH 


0029C6 












• ENTRY 


IJKSZCI 


0027E6 












• ENTRY 


IJKSZCP 


00291A 












ENTRY 


IJKSZCS 


002816 












• ENTRY 


IJKSZCT 


0029AC 












ENTRY 


IJKZMSA 


002A20 












* ENTRY 


IJKZWSI 


002B44 












CSECT 


IJJCPIN 


002680 


002680 










• ENTRY 


IJJCP3 


002680 








FLOATING POINT REGISTERS 



oooooooooooooooo 



0000000000000000 



oooooooooooooooo 



oooooooooooooooo 



RfcGO 


00003218 


7E002420 


000022A8 


00003278 


00002270 


000022CC 


0000318F 


0000 1 000 


REG8 


00002000 


00002400 


00002000 


00002000 


00002*80 


00003318 


00002428 


000027S8 



f 

H 
W 

I 

H 

H 
O 

H 



40-CSW KEY-00 ADDR-002040 ST AT SJS-0000 100000000000 COUNTrOOOOOO 



48-CAW KEY-00 ADDR-002038 



PSW CONTENTS 


EXTERNAL 


INTERRUPT 


SUPERVIS 


OR CALL 


PROGRAM 


CHECK 


MACHINE 


CHECK 


INPUT/OUTPUT 


r IELD ' FORMAT-OLD 18 


-NEW 58 


-OLD 20 


-NEW 60 


-OLD 28 


-NEW 68 


-OLD 30 


-NEW 70 


-OLD 38 


-NEW 78 


SYSTEM MASK 


BIT-llllllll 


-00000000 


-111 1 11 LI 


-00000000 


-llilllll 


-00000000 


-0101 1011 


-00000000 


-llilllll 


-00000000 


PKOTECTION KEY 


HEX-0 


-0 


-0 


-0 


-0 


-0 


-5 


-0 


-0 


-0 


AMWP 


BlT-0101 


-0100 


-0101 


-0100 


-0101 


-0100 


-1011 


-0000 


-0101 


-0100 


INTERRUPT CODE 


HEX-0000 


-0000 


-0000 


-0000 


-0007 


-0000 


-C2C5 


-0000 


-OOOC 


-0000 


INSTR LENGTH 


DEC-0 


-0 


-1 


-0 


-3 


-0 


-3 


-0 


-2 


-0 


CONDITION CODE 


DEC-0 


-0 


-0 


-0 


-2 


-0 


-1 


-0 


-0 


-0 


PROGRAM MASK 


BIT-0000 


-mi 


-IliO 


-0000 


-1110 


-0000 


-0110 


-0000 


-1110 


-0000 


INSTR ADDRESS 


HEX-000000 


-OOOGCO 


-0024CA 


-000B02 


-00248A 


-000C94 


-D1F340 


-0008F4 


-0024CA 


-000206 



4C-UNUSEO-00000000 



50-TIMER-FE9912FF 



54-UNUSED-00FFB342 
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*r 
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CO 


N) 
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tn 


CO 


• 
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<D 




3 


»ti 




F 


m 


V. 


H 


H 







iO 


CO 


H 


Q) 


0) 


9 


9 


•0 


§ 


H 


ft 


rt> 


H 




■ 


►a 


CO 


K 







<n 


iQ 


c 


H 


H» 


Qj 


a 


§ 


m 






<«* 




•ti 




ft> 




9 




H 




*r 









Hi 




H 




00 



DTF-A 
'INCARD' 
002000 


MASK FLAG _ UAIM 
\ . v r CHAIN 
V^(DTF-T) \ ADDR 
421002018 OIJ002AF8 


RCD _ MAI NT , 
FLAGSI LNGTH I WORD 
4500J004B IlOOOOOOOl 


A(BUFFER) 
00002050 


REMAIN 

IN 

BUFR JLNGTH 

004BP04B 


[START OF DTF TABLE 
100008000 oeoooooi 


002020 


00002038 


00002040 


000024B8 


02810202 


00002050 


00003008 


02002050 


2000004B 


002040 


47000000 


4700004B 


00000000 


00000000 


1 BUFFER 
1C940C104 


40C140C4 


C1E3C14C 


C3C109C4 


002060 


TO THE NEXT 


LINE ADDRESS CONTAINS 


5C5Q5C5C 










002080 
0020A0 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


5C5C5C07 


CI *34780 
04000002 


DTF-A 'OTCARD' 
220020B8 01002000 


45100050 


10000000 


00002140 


00500050 


00008400 


002 0C0 


000020E0 


00000000 


00002508 


04904141 


00002140 


40404040 


07004700 


00000040 


0020E0 


41002140 


20000050 


010020F0 


20000050 


40404040 


40404040 


40404040 


40404040 


002100 


TO THE NEXT 


LINE ADDRESS CONTAINS 


40404040 










002140 


C940C104 


40C140C4 


CIE3C140 


C3C109C4 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


5C5C5C5C 


002160 


TO THE NEXT 


LINE ADDRESS CONTAINS 


5C5C5C5C 










002180 


5C5C5C5C 


5C5C5C5C 


5C5C5CF0 


FOFOFOFl 


, STAHT 
I05F00700 


45E0F00A 


00002270 


58C0E000 


0021AO 


189F1831 


58F0C054 


05E041E0 


E00E051F 


010022A0 


00000198 


4110C044 


58F0C050 


0021C0 


05EF0203 


00503000 


4U0C010 


58F0C04C 


05EF4110 


C01458F0 


C04C05EF 


41E0013F 


002 1EO 


90EE0058 


18O058F0 


C0584110 


005805EF 


4U0D0F4 


5010C020 


4110C018 


58F0C040 


002200 


05EF4120 


C0304A20 


20000201 


C0600048 


4150C05C 


50502004 


92882004 


024A0148 


002220 


D0F4D204 


D193013F 


41100148 


5010C02C 


4110C024 


58F0C040 


05EF4IE0 


013F90EE 


002240 


D058180D 


58F0C064 


41100058 


05EF47F0 


905E4110 


C01058F0 


C04805EF 


4H0C014 


002260 


58F0C048 


05EF5800 


D00498EC 


D00C07FE 


00003000 


40005000 


60007000 


00000000 


002280 


80002000 


800020A0 


5B002000 


0000004B 


00003174 


230020AO 


00000050 


000031C8 


0022A0 


0008F8F8 


00002192 


0A002000 


880022CC 


000020E0 


8F0025B0 


000029C6 


000029BA 


0022CO 


00002DA0 


00002990 


000022F0 


00002192 


000100C0 


00002354 


00000000 


00000000 


0022E0 


FFFFFFFF 


FFFFFFFF 


OOFEFFFF 


OCOOCOOO 


■ SUB 1 
I90ECD00C 


45E0F00C 


000023B8 


58C0E000 


002300 


189FI831 


58F0C01C 


05E041EO 


E00E051F 


030023C8 


00000100 


0203D058 


30000203 


002320 


D0503C04 


58600058 


02046000 


C03D5850 


D05841E0 


500090EE 


O0tJ1800 


58F0C020 


002340 


41100060 


05EF58D0 


D00498EC 


000C07FE 


47F0909C 


1 REPEAT 
|90ECD00C 


45EOF00C 


000023B8 


002360 


58COEC0O 


5890C024 


183158F0 


C01C0700 


05E041E0 


E00E051F 


030023C8 


00000100 


002380 


D20 30058 


3000D203 


00503004 


58600058 


41E06000 


90EED060 


180D58F0 


C0204U0 


0023AO 


006005EF 


5800C004 


98EC000C 


07FE5800 


D00498EC 


DC0C07FE 


00003000 


40005000 


0023CO 


600070CO 


00000000 


000CF8F8 


000022F0 


00002354 


00002758 


00002400 


000022FO 


0023E0 


OCCOCCOO 


ooocoooo 


FFFFFFFF 


FFFFFFFF 


OOFEFFFF 


OCFOFOFO 


F0F002FF 


03FF09FF 


002400 


■ LAST 
|90fcCDC0C 


45E0FO0C 


00002480 


58C0E00C 


189F1831 


58FOC018 


05E041EO 


E00E051F 


002420 


03002490 


OOOCOltO 


0203D058 


30OOD2O3 


00503004 


5860D058 


F224D0E0 


6000F8FO 



o 

v 

c 
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to 



*3 
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H 
CO 

*0 



hi 

8 



&> 
H 
ft 
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O 
Hi 

H* 
00 



002440 


D060C035 


FAF20060 


DOE0F83F 


00E8D060 


92F9C012 


F8230070 


00E892F8 


C0125860 


002460 


0058F342 


60000070 


96F06004 


5800D004 


98ECD00C 


07FE58DO 


D00498EC 


900i07FE 


002480 
0024A0 


00003000 
OOOOOCOO 


40005000 
00000000 


60007000 
FFFFFFFF 


OOOOOOOO 
FFFFFFFF 


0008F8F8 
OOFEFFFF 


00002400 
OCICOOOO 


00002758 
ilJCFZIZO 
IOA320000 


OOOOOcOO 
0A32OOOO 


0024C0 


47F0F010 


OA3200OO 


0A009180 


10024710 


F01C0A07 


91011004 


4780F02C 


91401002 


0024E0 
002500 


4780F010 
07FE615C 


50E0F04C 
00002F40 


58E01020 
i IJCFZOZ4 
[OA320000 


0501F04A 
0A320000 


E0004770 
0A320000 


F04458E0 
50E0F0A4 


101C07FE 
0A009180 


58E0F04C 
10024710 


002520 


F01C0A07 


91101003 


4710F040 


02001030 


1028D201 


1036102E 


58E01028 


D24F1038 


002540 


E0O058E0 


F0A407FE 


41E10030 


5OE01008 


0A009180 


10024710 


F0540A07 


18E14110 


002560 


F078OA0O 


91B0F07A 


4710F066 


0A07181E 


41E10028 


50E01008 


47F0F010 


OOOOOOOO 


002580 
0025A0 


00000000 
E309E800 


00000004 
00000000 


00002590 
00000000 


OOOOOOOO 
OOOOOOOO 


09002598 
ilJKSYSA 
IA0002500 


OOOOOOOB 
OOOOOOOO 


F4FIF5F0 
81010078 


C94009C5 
OOOOOOOO 


0025C0 


00002600 


00000000 


00000000 


07000700 


00008400 


08000003 


000025F8 


OOOOOOOO 


O025E0 


03002680 


3100C901 


E2E8E203 


E2400040 


90002600 


47000000 


01002600 


20000079 


002600 


TO THE NEXT 


LINE ADDRESS CONTAINS 


40404040 










002660 


40404040 


40404040 


40404040 


40404040 


40404040 


40404040 


40000000 


OOOOOOOO 


002680 


00000000 


00000000 


47F0F00C 


9023F000 


91031015 


4770F066 


58301028 


06304120 


0026A0 


00091803 


43030000 


4332F0CB 


19034780 


F0364620 


F0284920 


F0CA47B0 


F046920B 


0026C0 


10284530 


F0A09180 


10154780 


F056947F 


10154530 


F0AO4122 


FOC 00200 


10282000 


0026E0 


06001028 


101E0A00 


91041015 


4780F07A 


4530F0A2 


92011028 


0A004530 


F0A29101 


002700 


10044780 


F09A9104 


10154710 


F09A9108 


101F4710 


F0AE58E0 


10189823 


F00007FE 


002720 
002740 


0A009180 
0BCBE38B 


10024710 
03014118 


F0AC0A07 
130B0004 


07F31821 
F9C3F14E 


48020006 
E5E660F0 


41101016 
4010C128 


0AO21812 

ilJKSZCN 
I905CF408 


47F0F09A 
58C0F2B4 


002760 


585D0008 


50D50004 


18AD18D5 


5A510004 


5550C29C 


47B0C07E 


50500008 


0200C2BA 


002780 


C2BB4850 


C29A1255 


4780C038 


485A0048 


41550001 


4050C29A 


40500048 


0203004C 


0027A0 


A0145851 


00005050 


0000D200 


50025003 


91030000 


4710C078 


4A550000 


96405004 


0027C0 
0027EO 
002800 


91805C04 
U000051F 
C2B89202 


4710C078 

.IJKSZCI 
210O|05F0 

C2B84780 


41550008 
58C0F224 
C0E892F1 


47F0C064 
9680C3EE 
C2959200 


985CC408 
5800C428 
C28F47F0 


07FE41F0 C0BE985C 

D2330014 C3F49500 

.IJKSZCS 
C27AP0EC D00C58C0 


C4089293 
C3EF4110 
F1F69200 


002820 


C2B8947F 


C3EE947F 


C39492FE 


C119185C 


91055C00 


474OC0F0 


58550004 


47FOC0D8 


002840 


920EC119 


47F0C0D6 


584500G0 


95061000 


A720C122 


02COC109 


10000COO 


C109C11B 


002860 


91004C02 


4710C122 


947FC3EE 


982C001C 


07FE0A11 


20408010 


04081865 


91036000 


0C2880 


4780C19B 


471CC152 


584600G0 


4A440000 


05004000 


10004780 


C15A9180 


40044710 
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H 




ft 
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H 




00 



0028AO 


C1524144 


000847F0 


C1385866 


000447F0 


C124950A 10004740 


C174950F 


10004720 


0028C0 


C174D502 


4001C3A1 


4770C142 


91404004 


4710C142 91104004 


4710C198 


91084004 


0028EO 


4780C110 


947FC394 


58140004 


47F0CICA 


950B1000 4770CIA8 


9640C394 


47F0CU0 














ilJKJZCP 


002900 


18619107 


C2BA92F4 


C2954710 


C1BA92F2 


C2959200 C28F47F0 


C27AI90EC 


000C58C0 


002920 


F0F2185O 


91055000 


4780C22A 


4740C1E0 


58550004 47F0CICC 


05011004 


50484770 


002940 


C 1081805 


58610000 


50600038 


4A610006 


50600010 58550000 


D2005002 


50039180 


002960 


C3EE4770 


C21498EC 


D00CO7FF 
ilJKSZCA 


947FC3EE 


0233C3F4 D014D202 
ilJKSZCM 


C3F10011 


50D0C4*8 


002980 


0A11451O 


COC62200 


I9207F08A 


45F0F0OC 


I9208F082 184C58C0 


F07C4700 


C24C4510 










iIJKSZCT 




ilJKTOPM 


0029A0 


C0BE230O 


9200C243 


47F0C438 


I05F092F3 


F03F9200 F03947F0 


F024|92F0 


F0339200 






ilJKTCLM 










0029C0 


F02D45FO 


F014J92F3 


F0279204 


F02190EC 


000C05F0 18514140 


F01C4100 


FIBC4110 










FLAG 


^DUMMY DSA ENDCORE j 
T-0000|0003k 00007FFO| 

1SGSW— JH <W N INVCT 

0000|08|08f\ 00002840 


CHAIN FRWDl 


A (IJKSZCT)! 


0029E0 


F0140A04 


47F10000 


5BC901D2 


E2F0F040 


00003080) 


000029AC| 




PROG MASK | 






K 






002A00 


OEOOOOOOl 


00002B44 


000027E6 


00002758 


00002868 


00002830 




SSA2 








SAVfc 






002A20 
002A40 


050000C0 


00000000 


00000000 


00000000 


00000000 00000000 


00000000 


00000000 


TO THE NEXT 


LINE AODRESS CONTAINS 


00000000 


















SSA1 






002A60 


00000000 


00000000 


00000000 


00000000 


05000000 00003080 


00000000 


.00002F40 


002A80 
002AA0 
002AC0 


000024B8 


00003080 


00002018 


00002050 


00002000 0000004B 


400021B0 


5BC02000 


0000004B 


00003174 


40002192 


00002000 


00002A20 00002DEO 


00000000 


OOCOOOOO 


TO THE NEXT 


LINE ADDRESS CONTAINS 


00000000 




CURRENT 


FILE CHAIN 






SCALE FACTOR -^ 


looooooloo 


DECIMAL INTEGER | 


FILE 


ANCHOR 


002AE0 


00000000 


00000000 


00000000 


00000000 ooooooool 


230020AC 


FEC020A0 




FORMAT • 


ENTRY POINT TABLE 










0O2B0O 
002B20 


TO THE NEXT 
00000000 


LINE AODRESS CONTAINS 


00000000 








00000000 


00000000 


00000000 


00000000 00000000 


00000000 


CO0O283C 




ilJKZWSI - 


NTERRUPT SAVE AREA REG 


REG 1 REG 2 


REG 3 


REG 4 


002B40 


A00025B0 

REG 5 


looooocooPswooooooool 


oooocooo 


00000000 OOOOCOOO 


00000000 


00000000 


REG 6 


REG 7 


REG 8 


REG 9 REG 10 


REG 11 


REG 12 


002B60 


000022CC 


000031BF 


00001000 


00002000 


00002400 00002000 


00002000 


00C02480 


REG 13 


REG 14 


REG 15 




(START OF 65 DOUBLE WORD PL/1 TRANSIENT AREA 


002B80 


00000000 


00000000 


OCOOOOOO 


oocccooo 


I18C118B0 41D040P0 


50B00004 


18950202 


OU2BA0 


00899001 


58800088 


91808000 


4780C0B4 


91808008 4780C03E 


91088004 


4780C03E 


002BC0 


96048004 


48100016 


02008019 


104E9140 


80044780 C04A9407 


80000600 


80009000 


002BE0 


94098009 


91428008 


4710C0BC 


58108CC0 


D7011000 10005820 


80104110 


Cl t >0D202 


0C2CC0 


C0798001 


4500C07C 


000020B8 


0A02S020 


80109680 80099101 


80094710 


C09A0202 


0U2C20 


80050080 


D202D080 


D089947F 


80009180 


90004199 OC044780 


C00E58D0 


000498EC 


C02C40 


O0OC07FE 


94FB8004 


47F0C09E 


91208000 


4710C05C ^8108000 


4UICC00 


95101014 


.002C60 


477OC05C 


D20BC144 


IOCOD203 


10000*0 


91801015 4710CCF0 


9207C138 


45^0C11E 


002C80 


9110101b 


923FC138 


4780C11C 


9227C13e 


45E0CUE 91011C04 


4710C114 


92 3 7C 138 


002CA0 


45E0CUE 


D20B1000 


C14447F0 


C0824120 


C1385021 00080AOO 


91801002 


47 IOC 132 
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(+ 
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H* 
00 



002CC0 


0A0707FE 


00000000 


07000000 


20000001 


00000400 


00000100 


00000138 


00000000 


002CE0 


•5B5BC206 


D7C50540 


ooooeooo 


00000000 


00000000 


00000000 


00000000 


00000000 


002000 


TO THE NEXT 


LINE A0DRESS CONTAINS 


00000000 










002080 


18C 19834 
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Glossary 



For a more complete list, of data processing 
terms, refer to IBM Data Processing 
Techniques, A Data Processing Glossary , 
GC20-1699. 

access method ; Any of the data management 



techniques (sequential, indexed sequential, 
or direct) available to the user for 
transferring data between main storage and 
an input/output device. 

ASCII (American National Standard Code for 
Information Interchange) ; A 128-character, 
7- bit code. The high-order bit in the 
System/360 8-bit environment is zero. 

asynchronous : Without regular time 
relationship. The user's programs run 
asynchronously with the I/O interrupts. 
BTAM's channel appendage routine runs 
synchronously with the I/O interrupts. 

background program ; In multiprogramming, 
the background program is the program with 
lowest priority. Background programs 
execute from a stacked job input. 

batched job ; Programs that execute from a 
stacked job input. Batched jobs run under 
the control of job control. 

block ; 



1. To group records physically for the 
purpose of conserving storage space or 
increasing the efficiency of access or 
processing. 

2. A physical record on tape or DASD. 
BTAM (Basic Telecommunications Access 



Method) ; A basic access method that 
permits a READ/WRITE communication with 
remote devices. 

catalog ; To enter a phase, module, or book 
into one of the system libraries. 

CCB ; See Command Control Block . 

CCH ; See Channel Check Handler . 

Channel Check Handler (CCH) ; A feature 



that assesses System/370 channel errors to 
determine if the system can continue 
operations . 

channel program ; One or more Channel 
Command Words (CCWs) that control (s) a 
specific sequence of channel operations. 
Execution of the specific sequence is 
initiated by a single start I/O 
in str uc t ion . 



checkpoint record ; A record containing the 
status of the job and of the system at the 
time the checkpoint routine writes the 
record. This record provides the necessary 
information for restarting a job without 
returning to the beginning of the job. 



checkpoint/restart ; A means of restarting 
execution of a program at some point other 
that the beginning. When a checkpoint 
macro instruction is issued in a problem 
program, checkpoint records are created. 
These records contain the status of the 
program and the machine. When it is 
necessary to restart a program at a point 
other than the beginning, the restart 
procedure uses the checkpoint records to 
reinitialize the system. 



checkpoint routine ; A routine that records 
information for a checkpoint. 

Command Control Block (CCB) ; A 16-byte 



field required for each channel program 
executed by physical IOCS. This field is 
used for communication between physical 
IOCS and the problem program. 

communications region ; An area of the 
supervisor set aside for interprograra and 
intraprogram communication. It contains 
information useful to both the supervisor 
and the problem program. 

control program ; A group of programs that 
provides functions such as the handling of 
input/output operations, error detection 
and recovery, program loading, and 
communication between the program and the 
operator. IPL, supervisor, and job control 
make up the control program in the Disk and 
Tape Operating Systems. 

core storage ; See main storage . 



data file; A collection of related data 



records organized in a specific manner. 
For example, a payroll file (one record for 
each employee, showing his rate of pay, 
deductions, etc) or an inventory file (one 
record for each inventory item, showing the 
cost, selling price, number in stock, etc). 

data protection ; A safeguard invoked to 
prevent the loss or destruction of customer 
data. 

data set security ; A feature that provides 
protection for disk files. A data secured 
file cannot be accidentally accessed by a 
problem program. 
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Disk Operating System (DOS) : A disk 
resident programming system that provides 
operating system capabilities for 16K and 
larger IBM System/360 and IBM System/370. 

DOS ; See Disk Operating System . 

DOS Volume Statistics ; A facility that 
monitors and records the number of 
temporary read and write errors on 
currently accessed tape volumes. This 
facility has two options. Error Statistics 
by Tape Volume (ESTV) and Error Volume 
Analysis (EVA) . 

DTF (define the file) macro instruction ; A 
macro instruction that describes the 
characteristics of a logical input/output 
file, indicates the type of processing for 
the file, and specifies the main storage 
area and routines to process the file. To 
do this, use the appropriate entries in the 
keyword operands associated with the DTF 
macro instruction. 

Environmental Recording f Editing, and 
Printing (EREP) ; A program that edits and 
prints data that has been stored on the 
system recorder file. 

EREP ; See Environmental Recording, 
Editing, and Printing . 

Error Statistics by Tape Volume (ESTV) ; 
One of the two options of the DOS volume 
Statistics. With ESTV support, the system 
collects data on tape errors by volume for 
any tape volumes used by the system. 

Error Volume Analysis (EVA) ; One of the 
two options of the DOS Volume statistics. 
With this option, the system issues a 
message to the operator when a number of 
temporary read or write errors (specified 
by the user at system generation time) has 
been exceeded on a currently accessed tape 
volume. 

ESTV ; See Error Statistics by Tape Volume . 

EVA ; See Error Volume Analysis . 

extent ; The physical locations on 
Input/Output devices occupied by or 
reserved for a particular file. 

fetch ; 

1 . To bring a program phase into main 
storage from a core image library for 
immediate execution. 

2. The routine that retrieves requested 
phases and loads them into main storage 
(see system loader ) . 

3. The name of a macro instruction (FETCH) 
used to tranfer control to the system 
loader. 



4. To transfer control to the system 
loader. 



Fetch/Load Trace (F/L Trace) ; A program 



that records information about phases and 
transients as they are called from the core 
image library. 



file; See data file. 



fixed length record ; A record having the 
same length as all other records with which 
it is logically or physically associated. 

F/L Trace: See Fetch/Load Trace. 



foreground initiation : A set of system 
routines to process operator commands for 
initiation of a foreground program. 

foreground program ; In multiprogramming, 
foreground programs are the highest 
priority programs. Foreground programs may 
be executed from a job stack or in an SPI 
environment . 

Forms Control Buffer (FCB) : The buffer in 



the IBM 3811 Printer Control Unit that 
stores carriage control information for the 
IBM 3211 Printer. 

Generalized Supervisor Calls Trace (GSVC 
Trace) : A program that records SVC 
interrupts as they occur. All or a 
selected group of SVCs can be traced. 

GSVC Trace; See Generalized Supervisor 



Calls Trace. 



IDRA: See Independent Directory Read- in 



Area . 

Independent Directory Read-in Area (IDRA) : 
A resident area, created by supervisor 
option, into which the system reads core 
image library directories for fetch and 
load operations. Using IDRA frees the 
physical transient area to perform error 
recovery procedures. 

initial Program Load (IPL) ; The 
initialization procedure that causes Disk 
and Tape Operating Systems to commence 
operation. 

interrupt ; A break in the normal sequence 
of instruction execution. It causes an 
automatic transfer to a preset storage 
location where appropriate action is taken. 

IOCS (Input/Output Control System) : A 
group of macro instruction routines 
provided by IBM for handling the transfer 
of data between main storage and external 
storage devices. 
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I/O (input/output) error logging ; The 
process of recording OBR and SDR records or 
the system recorder file. 

I/O Trace (Input/Output Trace) : A program 
that records I/O device activity for all or 
a selected group of I/O devices. 

IPL: See Initial Program Load . 

Job Accounting Interface ; A program that 
accumulates accounting information for each 
job step to: charge usage of the system, 
help plan new applications, and help 
supervise system operation more 
efficiently. 

Job Accounting Table ; An area in the 
supervisor where accounting information is 
accumulated for the user. 

job control : A program that is called into 
storage to prepare each job or job step to 
be run. Some of its functions are to 
assign I/O devices to certain symbolic 
names, set switches for program use, log 
(or print) job control statements, and 
fetch the first program phase of each job 
step. 

job step : The execution of a single 
processing program. 



Ks 



102H. 



language translators : A general term for 
any assembler, compiler, or other routine 
that accepts statements in one language and 
produces equivalent machine language 
instructions. For example. Assembler, 
COBOL, etc are language translators. 

librarian : The set of programs that 
maintains, services, and organizes the 
system libraries. 

library : An organized collection of 
programs, source statements, or object 
modules maintained on the system resident 
device. Three libraries are used by the 
Disk and Tape Operating Systems : core 
image library, source statement library, 
and relocatable library. 

linkage editor : A system service program 
that edits the output of language 
translators and produces executable program 
phases. It relocates programs or program 
sections and links together separately 
assembled (or compiled) sections. 

load : To fetch, i.e., to read a phase into 
main storage returning control to the 
calling phase. 

logical IOCS : A comprehensive set of macro 
instruction routines provided to handle 
creation, retrieval, and maintenance of 



data files. 



LSERV (label cylinder display) : A program 
that formats a listing of the label 
cylinder located on SYSRES. LSERV can run 
in and partition any outputs the list on 
SYSLST, which may be assigned to disk, 
tape, or printer. 



Machine Check Analysis and Recording 
(MCAR) : A feature that records System/ 370 
machine check interrupt error information 
on the system recorder file and then 
attempts to recover from the interrupt. 

main storage : All addressable storage from 
which instructions can be executed or from 
which data can be loaded directly into 
registers . 

MPS : See multiprogramming system . 

multiplexer channel : A channel designed to 
operate with a number of I/O devices 
simultaneously on a byte basis. That is, 
several I/O devices can be transferring 
records over the multiplexer channel, time 
sharing it on a byte basis. 

multiprogramming system : A system that 
controls more than one program 
simultaneously by interleaving their 
execution. 

multitask operation : Multiprogramming ; 
called multitask operation to express not 
only concurrent execution of one or more 
programs in a partition, but also of a 
single reenterable program used by many 
tasks . 

OBR : See outboard recorder . 

OLTEP : See On-Line Test Executive Program . 

On-Line Test Executive Program (OLTEP) : 
The control program of the on-line test 
system. OLTEP is the interface between the 
on-line test and the operating system. 

outboard recorder (OBR) : A feature that 
records pertinent data on the system 
recorder file when an unrecoverable I/O 
error occurs. 

overlap ; To do something at the same time 
that something else is being done; for 
example, to perform input/output operations 
while instructions are being executed by 
the central processing unit. 

overlay : A program segment (phase) that is 
loaded into main storage. It replaces all 
or part of a previously retrieved section. 

PCIL : See Private Core Image Library . 
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PDAID: See Problem Determination Aids. 



phase ; The smallest complete unit that can 
be referenced in a core image library. 
Each program overlay is a complete phase. 
If the program has no overlays, the program 
itself is a complete phase. 

physical IOCS : Macro instructions and 
supervisor routines (Channel Scheduler) 
that schedule and supervise the execution 
of channel programs. Physical IOCS 
controls the actual transfer of records 
between the external storage medium and 
main storage, and provides I/O device error 
recovery. 

Private Core Image Library (PCIL) : A file 
reference in the same manner and for the 
same purpose as the system core image 
library, but distinct from the system core 
image library. PCIL increases available 
core image library space to enable 
compiling, linkage editing, and executing 
in the foreground partition, when a private 
core image library is assigned to that 
foreground partition. 

private library : A core image, 
relocatable, or source statement library 
that is separate and distinct from the 
system library. 

problem determination : A procedure or 
process (provided by IBM) that the user can 
follow after an error message to determine 
the cause of the error. 

Problem Determination Aids (PDAID) : 



Programs that trace a specified event when 
it occurs during the operation of a 
program. The traces provided are: QTAM 
Trace, I/O Trace, F/L Trace, and GSVC 
Trace . 

QTAM Trace : A program that records certain 
supervisor and I/O activities on tape or in 
main storage. 

RDE : See Reliability Data Extractor . 

record : A general term for any unit of 
data that is distinct from all others when 
considered in a particular context. 

© 

Recovery Management Support (RMS) : A 
feature for System/370 that consists of the 
MCAR (Machine Check Analysis and Recording) 
and CCH (Channel Check Handler) functions. 
RMS gathers information about System/370 
hardware reliability and attempts certain 
error recovery operations. RMS is a part 
of the entire reliability, availability, 
and serviceability support for System/370. 

Reliability Data Extractor (RDE) : A 
function that provides hardware reliability 
data that is analyzed by IBM. 



relocatable: A module or control section 



whose address constants can be modified to 
compensate for a change in origin. 

restart : See checkpoint/restart. 



RMS : See Recovery Management Support . 



SDR (statistical data recorder) : A feature 
that records the cumulative error status of 
an I/O device on the system recorder file. 



selector channel : A channel designed to 
operate with only one I/O device at a time. 
Once the I/O device is selected, a complete 
record is transferred one byte at a time. 

self -relocating : A programmed routine that 
is loaded at any doubleword boundary and 
can adjust its address values so as to be 
executed at that location- 

self -relocating program : A program that is 
able to run in any area of storage by 
having an initialization routine to modify 
all address constants at object time. 

Single Program Initiator (SPI) : Under DOS, 
a program that is called into storage to 
perform job control type functions for 
foreground programs not executing in batch 
job mode. 

SORTED DSERV : A program that gives you an 



alphamerically sorted listing of any or all 
of the library directories. 

SPI : See Single Program Initiator . 



stand-alone dump : A program that displays 
the contents of main storage from a minimum 
of 8K bytes to a maximum of 16384K bytes. 
It helps to determine the cause of an 
error. 

supervisor : A component of the control 
program. It consists of routines to 
control the functions of program loading, 
machine interruptions, external 
interruptions, operator communications and 
physical IOCS requests and interruptions. 
The supervisor alone operates in the 
privileged (supervisor) state. It coexists 
in main storage with problem programs. 

system residence : The external storage 
space allocated for storing the basic 
operating system. It refers to an on-line 
tape reel or disk pack that contains the 
necessary programs required for executing a 
job on the data processing system. 

task selection : The supervisor mechanism 



for determining which program should gain 
control of CPU processing. 
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telecommunications : A general term 
expressing data transmission between remote 
locations . 

teleprocessing ; A term associated with IBM 
telecommunications systems expressing data 
transmission between a computer and remote 
devices . 



trace : 



1. 



To record a series of events as they 
occur. 



2 . The record of a series of events . 

track hold ; A function for protecting DASD 
tracks that are currently being processed. 
When track hold is specified in the DTF f a 
track that is being modified by a task in 
one partition cannot be concurrently 
accessed by a task or subtask in another 
partition. 

transient area ; This is a main storage 
area (within the supervisor area) used for 
temporary storage of transient routines. 

transient routines ; These self-relocating 
routines are permanently stored on the 
system residence device and loaded (by the 



supervisor) into the transient area when 
needed for execution. 



UCS; 



See Universal Character Set. 



UCSB; See Universal Character Set Buffer. 



undefined record ; A record having an 
unspecified or unknown length. 

Universal Character Set ; A printer feature 
that permits the use of a variety of 
character arrays. 

Universal Character Set Buffer (UCSB) ; A 



buffer in a printer control unit that 
stores the code equivalents of the 
characters on an interchangeable print 
chain or train cartridge. 

variable length record ; A record having a 
length independent of the length of other 
records with which it is logically or 
physically associated. (Contrasted with 
fixed length record .) It contains fields 
specifying physical and logical record 
lengths. 
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Index 



Indexes to systems reference library 
manuals are consolidated in the publication 
DOS Master Index , GC24-5063. For 
additional information about any subject 
listed below, refer to other publications 
for the same subject in the Master Index. 
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